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Introducing ProtoGen+. Visual tools with the most awesome 
workbench ever created for Windows development. 


Discover the ease and 
productivity of visual 
development! 


Visually 

develop 

screens 


he future has arrived—a complete 
point-and-click, WYSIWYG 
workbench that lets you create 
dazzling applications without 
writing a line of code. 

Paint your 
screens. Design 
a menu and link 
screens togeth¬ 
er. Test the flow 
in a live environ¬ 
ment, and gen¬ 
erate code for 
ANSI C, C++ 
for OWL or MFC 
or Pascal with 
objects. It's that 
easy. 

And this 

open! ProtoGen+ 
will work with 
your database, 
compiler, 
libraries and extensions. Powerful 
add-on features, like SQLView offer 



Instantly generate 
source code in 
Pascal, C or C++ 


ETeTbI 


workbench access to multiple 
databases to develop client/server and 
xBase applications. Snap-in compo¬ 
nents make ProtoGen+ open to future 
development technologies—whatever 
they may be. 

ProtoGen+ is easy to learn, 
speeds your development cycle and 
protects your investment by generat¬ 
ing C,C++ and Pascal. We guarantee 
you'll 
prototype 
and generate 
exciting 
applications 
faster than 


The most powerful, open set of 
Visual Development Tools ever! 
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Point-and-click to paint 
screens with bitmaps, 
icons, tables, data valida¬ 
tion, custom colors, fonts, 
3D effects, visual tool¬ 
bars, status lines, balloon 
help. MDI and more! 


you ever 

thought 

possible! 
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Output C, 
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Objects 
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Data valida¬ 
tion, 3-D 
effects. MDI 
and more 

Rich library 
of visual 
control 
objects 
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Code 
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License our technology to 
create new code generators 


Fasten your seatbelt 
for ProtoGen+! 


Only 


(list price 
$395) 


Bring your applications to life using the latest 
visual design tools! 
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The Visual Development Edge™ 

All products named are trademarks of their 
respective companies. ©1993 ProtoView Development 


$199 

1 - 800 - 231-8588 

Ask for Ext. 60 
In NJ, call (908) 329-8588 
ProtoGen+'s SQLView access to multiple 
databases is available at an additional price; 
ask about it when you call. 
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No matter what database they throw at you, 
you’ll connect with Q+E ODBC Pack. 


Fastball, slider, or change-up. 
dBASE, Paradox, or Oracle. If you want 
to connect, you know you’ve got to 
react fast. 

With the comprehensive lineup 
of over 20 drivers in Q+E ODBC Pack, 
you can. 

Cover all your bases with Q+E. 

Drivers are the critical link between 
your ODBC-compliant applications, 
your network, and your databases. And 
because their quality directly affects the 
performance of your applications, it’s 
vital that you have superior drivers. 

Don’t risk costly errors. Rely on 
Q+E Software for fast, dependable 
drivers. 

Q+E ODBC Pack delivers: 

• Comprehensive coverage: Connect aU 
ODBC-compliant applications to aU 
major SQL and PC DBMS with Q+E 
ODBC Pack. 



• Consistent access: Q+E ODBC Pack 
drivers make all databases look the same 
so you don’t have to change the way you 
work every time you change databases. 

• State-of-the-art technology: Q+E ODBC 
Pack gives you the same database access 
technology used by leading software 
publishers. Plus all drivers are certified 
through Q+E Software’s ODBC Verifi¬ 
cation Suite. 

• High-level implementation: With Q+E 
ODBC Pack you get full SQL, transac¬ 
tion processing, and even network lock¬ 
ing support for non-SQL DBMS. And 
it’s the only set of drivers that sports a 


consistent level of ODBC ' 4T 
Core, Level 1, and selected Level 2 
functions. 

• One-stop, cross-platform support: No 
other set of ODBC drivers offers the 
range of support available from Q+E 
Software. Support is available for 
Windows; support for OS/2, Windows 
NT, Macintosh, and Solaris will be 
available in early 1994. 

Complete, dependable, and quick, 

Q+E ODBC Pack makes sure your applica¬ 
tions perform—no matter what 
database you have to face. 


Q.+E ODBC Pack provides support for the following databases. 

Oracle, Sybase, Microsoft SQL Server, dBASE, INGRES, Paradox, DB2, SQL/400*, Btrieve, 
DB2/2, INFORMIX, NetWare SQL, Excel .XLS files, text files, PROGRESS, XOB, SQLBase, 
SQL/DS*, Teradata*, HP ALLBASE, and HP IMAGE/SQL; gateways: Micro Decisionware 
and DB2/2-DDCS/2 (‘requires a gateway), 

Q+E ODBC Pack drivers link all ODBC-compliant applications, 
including the following, to all major SQL and PC databases. 

Excel 5, Access, Visual Basic, PowerBuilder 3, WinWord 6.0, Lotus 1-2-3 Rel. 4, report 
writers, query and reporting tools, and many others. 



Try Q+E ODBC Pack for 
30 days, risk-free ! 

Make sure your ODBC-com¬ 
pliant applications work tomorrow. 
Put Q+E ODBC Pack on your 
t^am today! Purchase directly from 
Q+E Software. At only $199 . it’s a 
steal! 

If you are not completely sat¬ 
isfied, return it within 30 days for a 
full refund. No hassles. 

No delays. No errors. 

Call 1-800-876-3101 

Ext. DO 19 
8 am to 8 pm EST 


Qi 


® Database 
Access for 
Client Server 
Computing™ 


Q.+E Software 

5540 Centerview Drive, Suite 324 • Raleigh, NC 27606 
800-876-3101, (919) 859-2220, Fax (919) 859-9334 
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Virtualizing a DOS Device Driver with a VxD 


Windows applications can access your DOS device driver, but they pay a penalty. 

This article shows how writing a VxD to emulate the INT 21 h DOS device driver interface 
can help you avoid performance bottlenecks. 

Paula Tomlinson 


A VxD to Monitor DOS Output. 23 

DOS boxes can be used to offload CPU-intensive tasks from Windows. For example, Visual 
C++ runs its compiler in a hidden DOS box. It can be very useful, therefore, to be able to in¬ 
tercept standard output and standard error from a DOS task. This article shows how to cre¬ 
ate a VxD to do the trick. 

Paul Bonneau 



Windows Multimedia: Part 3 — Blocks Effect and Palette Fade-In . . 45 

Charles continues his look at using special effects to display bitmaps. This installment first 
shows how to display a bitmap by randomly BitBlt()’ing tiny blocks of it. Next, he shows how 
to use palette animation to make the bitmap appear to fade into view. 

Charles Mirho 



Tech Tips: Graying Window Regions, Centering Dialog Box Text, 
and Dual-Mode Apps. . 53 

Gregory C. Peters shows how he uses bitmaps to produce a disabled look for bitmaps that may 
contain both graphics and text. Scott Gourtey discusses the trick he uses for keeping text cen¬ 
tered in dialog boxes. Finally, if your linker refuses to accept a large DOS .exe for the DOS stub 
of a Windows executable, Paul Bixel provides a utility to do the trick. 

Leor Zolman 

Windows Questions & Answers .... . 63 

Kent Bair asks a question that allows Paul to explain the arcane subject of listbox sizing in 
Windows. Luis Castro asks how to remap his keyboard (e.g., redefine the extra Enter key to 
be the Tab key); it’s not simple, but Paul explains the issues and provides a DLL to do the 
trick. Finally, Paul starts his own bug of the month award, to be given out to buggy Windows 
device drivers that make life hard for all applications. This month’s winner is the standard 
VGA driver. 

Paul Bonneau 
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Practical C++: WUIMAN’S User Interface. 79 

This installment discusses WUIMAN’s algorithm for attribute inheritance, which lets the user 
interface designer create styles (such as button fonts and colors) that can be easily 
changed. The Bug++ of the Month goes to Borland for their devastating DLL bug, 
but Microsoft and Symantec win honorable mention for their poor support for 
static destructors in DLLs. 

Ron Burk 
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Sourcer, 


"Sourcer is the best disassembler 
we’ve ever seen." pc Magazine 


O' 


Creates commented source code and list¬ 
ings from binary files. Shows how programs 
work with detailed comments on interrupts, 
subfunctions, I/O functions, and more. Sup¬ 
ports all instructions to 80486 and V20/V30. 

Sourcer provides the best analysis separat¬ 
ing code and data. It automatically deter¬ 
mines data types, uses descriptive labels for 
BIOS and PSP data, and links data items 
across multiple segments. 


New version 5.0 makes most DOS EXE and 
COM files and drivers reassemble perfectly, 
byte-for-byte identical to the original! 


\ 


Top professionals depend on Sourcer for the 
mosueliable results with the least effort. 
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for Windows 


"Sourcer combined with Windows 
Source should be mandatory for 
looking into Windows Programs." 
Sal Ricciardi PC Magazine 


Windows Source™ with Sourcer generates 
detailed listings of Windows EXEs, DLLs, 
SYSs, VxDs, device drivers & OS/2 NE files. 
Labels, by name, export & import function 
calls, API calls like "GetFreeSpace" and more. 

See the many undocumented Windows 
functions used by professionals to perform 
tricks that are otherwise impossible. 


Comes complete with extra utilities for 
resource extraction and import analysis. 
Uses CodeView symbols for improved clarity. 



for PS/2, AT, XT, PC and Clones 

The BIOS Pre-Processor ™ with Sourcer 
creates commented listings for any BIOS 
ROM in your PC. Understand how your 
specific BIOS works! Adds over 75K of 
comments specific to your BIOS. Identifies 
multiple interrupt branches with special 
labeling like "int_10_video.‘ Fully automatic. 

Sourcer -Commenting Disassembler $129.95 
Sourcer w/BIOS -(save $10) 169.95 

ASMtool 486 -Automatic flowcharter 199.95 
ASM Checker -Finds source code bugs 99.95 
Windows Source -requires Sourcer 129.95 
Windows Source & Sourcer-(save $30) 229.90 

Shipping: USA $6; Canada/Mexico $10; Other $18. CA 
residents add sales tax. © 1993 VISA/MasterCard/COD 

30-DAY MONEY-BACK GUARANTEE 

1 - 800 - 648-8266 order desk 

V Communications, Inc. 

4320 Stevens Creek Blvd., Suite 275-WD 
San Jose, CA 95129 FAX 408-296-4441 
408-296-4224 




From 

the Editor 


This month's theme is device drivers. I keep thinking this topic is going to 
become unimportant, but I keep getting fooled. When device drivers appeared 
in DOS originally, they seemed like a dud. The problem was that memory was 
scarce and the only way to remove a device driver you weren't using from 
memory was by changing config.sys and rebooting. So, instead of using a 
device driver to talk to the screen, we all wrote directly to video memory, and 
instead of using a device driver to talk to the COM port, every package con¬ 
tained its own unique serial port I/O code - just the situation that device driv¬ 
ers were meant to avert. 

I thought we could pretty much write off DOS device drivers, but program¬ 
mers continued to be fascinated with them. Programmers tore apart DOS and 
figured out how to dynamically insert and remove their device drivers at run¬ 
time. In fact, the line between TSRs and device drivers has gotten somewhat 
blurry. In any case, programmers still seemed pretty interested in reading arti¬ 
cles related to DOS device drivers. 

Windows introduced its own style of device drivers, VxDS, in order to arbi¬ 
trate access to PC hardware from multiple applications (both DOS and Win¬ 
dows applications) at the same time. However, most VxDS being written today 
have little to do with virtualizing hardware devices. The reason is that Mi¬ 
crosoft made their VxD interface a dumping ground for all kinds of low-level 
system services. In particular, anytime a Windows program and a DOS pro¬ 
gram need to have any kind of interaction, a VxD is probably the best solu¬ 
tion. 

But surely Windows NT spells the end of device drivers as an outlet for 
tinkering and tampering. After all, with its system security and separate address 
spaces, surely programmers will be content to use a handful of device drivers 
delivered With the system. Not so! Windows NT 'filter drivers' let you insert 
your own nefarious code into the system, much like hooking into I NT 21h (for 
example, you could create a filter driver that displayed all the currently open 
files in the system). Once again, I think programmers will find ways to take 
advantage of device drivers to accomplish deeds that the operating system 
designers never intended (or at least never intended to encourage). 

With this issue, I believe we now hold the distinction of having published 
more VxDS than any other magazine in the world. Since there are still no good 
books on the subject of writing VxDS, I expect we will have one or two more 
VxD articles before the year is out. And if the past is any indication, device 
drivers will still be an important theme for years to come. 


Ron Burk 

Editor 

CIS: 70302,2566; Internet: ronb@rdpub.com ("... !uunet!rdpub!ronb") 
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Develop 

Windows Applications 
Quickly and Easily 


Phase3 Has Everything You Need 


Visual Development 

The Phase3 visual development environment 
provides a comprehensive suite of tools for 
screen creation. All standard Windows 
screen objects - push buttons, radio buttons, 
dialog boxes, etc. - are selectable from icon 
bars and are dynamically placed and sized 
on the screen as appropriate for the 
application. Standard Windows APIs are 
available from list boxes and are supported 
with on-line documentation. 


Phase3 Database 

Phase3 includes a relationally complete 
database supplied as a Windows DLL. The 
database supports complex data relation¬ 
ships and access and data manipulation by 
any language through a comprehensive 
suite of supplied database routines. 
Database integrity is enhanced with 
rollback recovery and transaction control. 
The Phase3 data dictionary simplifies data 
model definition and maintenance. 


Query and Reporting 

The Report Writer includes standard 
features like flexible headers, footers, free 
text, calculated fields, sort group sections 
and breaks, and subtotals. Reports can also 
include bitmaps of drawings and photo¬ 
graphic images. Queries are executed with 
the Database Browser which also allows 
data entry and manipulation. Railway 
diagrams assist in query creation, prompt¬ 
ing the user for appropriate selections and 
eliminating syntactical errors. 



Royalty-Free Applications 

Windows is a trademark of Microsoft Corporation. Turbo Pascal 
for Windows and Borland Pascal 7.0 are trademarks of Borland 
International, Inc. All other trademarks or service marks are 
recognized as the property of their respective owners. 


Lower CASE, E-R Modeling 

Phase3 automates logical data model design 
with Entity-Relationship modeling. After a 
user describes entity relationships graphi¬ 
cally and enters field descriptions, Phase3 
generates the physical database based on an 
analysis of the entity relationships. Phase3 
automatically includes foreign keys in 
appropriate tables and restructures the 
database as requirements change. Phase3 
suggests appropriate referential integrity 
constraints to be enforced at runtime. 


Hierarchy Chart 

Phase3 maintains a graphical map of an entire 
application. The Hierarchy Chart includes all 
windows, dialogs, reports, and code routines. 
To access the underlying C or Pascal source 
code, simply point-and-click on any node. 
Phase3 generated source is easily accessed 
and extended with user written routines. User 
code is preserved even if an application is 
regenerated. The Hierarchy Chart and E-R 
Diagram provide instant core documentation 
for an application. 


Help Generator 

The Phase3 Help Generator allows the easy 
creation of a complete Windows application 
help subsystem including context sensitive 
on-line help. The Help Generator includes its 
own text editor that gives complete control 
over the content, appearance, and branching 
logic through highlighted trigger text. Phase3 
generates a Windows compatible file with an 
“.HLP” extension that is then accessible 
from within the Phase3 created application. 
No other external tools are required. 


"... a thoroughly remarkable product... 
very impressive” 

Jeff Duntemann 

PC Techniques 

▲ ▲ ▲ 

“I was very impressed with Phase3, and using it 
made me wish i had learned Windows programming 
with a tool like this. Now that I know what it has to 
offer, I’ll probably use it to build the frame for most 
ot my programs.” 

L. John Ribar 

Windows Tech Journal 

▲ ▲ A 

“Phase3 hides the complexity of Windows program¬ 
ming but still allows an experienced programmer to 
drill down and extend generated C or Pascal source 
code, providing ultimate control.” 

Randy Goodhew 

Computer Software Columnist 

AAA 

“Phase3 takes an intuitive, innovative approach to 
developing Windows applications. It’s a pleasure to 
work with and has greatly boosted our productivity. 
One of the most important issues for us is that their 
technical support is excellent.” 

Reuben Halevi 

ISoft O&M 

AAA 

“It’s easy to put together an application with Phase3 
-everything's integrated. And the Phase3 database 
is terrific. It’s closer to true relational than anything 
we’ve found.” 

Michael Erickson 

Prism Business Solutions 


lo 



Order Now 

800 - 851-5650 

Or Call for Free Demo Disk 
Fax (805) 641-9083 


CALL NOW FOR COMPETITIVE UPGRADE PRICING 
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Device Drivers 


Virtualizing a DOS Device 
Driver with a VxD 

Paula Tomlinson 


Windows offers backward compatibility with DOS devices by providing ac¬ 
cess to DOS device drivers from within Windows. However, Windows applica¬ 
tions pay a significant performance penalty for using DOS device drivers to 
perform I/O. There are several factors working against DOS device drivers in 
the Windows environment but each one can be resolved, or at the very least 
minimized, by using a VxD. This article provides a VxD framework that you can 
extend to replace an existing DOS device driver, resulting in faster access times 
without any source code changes to calling applications 

How Windows Supports DOS Device Drivers 

DOS device drivers reside in (and can only access data in) the first 1 Mb of 
memory, while Windows applications run in extended memory. To accommo¬ 
date this discrepancy, Windows (via DOSMGR) provides a translation buffer be¬ 
low the 1 Mb memory line. DOSMGR breaks requests (such as a file read) into 
8Kb (4Kb in Windows 3.0) buffers and copies them from extended memory to 
the translation buffer in low memory, or vice versa on the way back. This 
process requires translation from a linear address to a segment:offset address 
and back. It also requires switching the processor into real mode before execut¬ 
ing any DOS code or code in the DOS device driver. The extra memory copy, 
the address translation, and the processor switch, in addition to the added 
overhead of negotiating communication with your device multiple times, can 
result in a significant performance hit. 

As I'll show later, interrupts are not reflected directly to the DOS device 
driver. The time it takes for the file I/O request (in the form of an INT 21h call) 
to reach the interrupt routine in the DOS device driver is dependent on the 
nuances of the Windows scheduler, the current state of the running virtual 
machines, and the time required for the processor to perform a ring transition. 
Again, the overhead can be costly. 


Paula Tomlinson received an Electrical Engineering degree from Colorado State Univer¬ 
sity. For the past six years she has developed various DOS, Windows, and Windows 
NT-based drivers and commercial applications for the HP ScanJet scanners, the HP 
LaserJet Fax, and the HP DeskJet printers. She is currently working on a book tenta¬ 
tively titled Writing Device Drivers for Windows NT. The opinions expressed in this arti¬ 
cle are hers alone and do not necessarily reflect the opinions of Hewlett-Packard. Send 
questions or correspondence to Paula via internet as paulat@vcd.hp.com. 
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LAUNCH BAR 


SIMPLIFIED RUN MENU 


HISTORY 


FrontRunner’s Launch Bar offers Run Menu offers Program Manager functionality Scroll to view the complete 

one-button launching of your favorite without navigating through all those open windows! history of your DOS session, 

applications. Customize it any way . 



Or To Get Your 
Free Demo! 
1 - 800 - 292 - 962 ! 


you like! 

COPY & PASTE 

Just highlight and click to copy and 
paste any part of your DOS session into 
a Windows or DOS program. 

COMMAND LINE POWER 

Run DOS or Windows programs right 
from the DOS prompt! 

• 

POWERFUL REAL TIME 
STATUS BAR 

FrontRunner’s Status Bar displays 
real-time information including 
system resources... and lets you 
write modules to display your own 
up-to-date information! . 
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Bringing the best of DOS to 
Windows ••• And the Power 
of Windows to DOS 

Frustrated with switching between 
Windows and DOS applications? Now 
you can get the command-line power 
you need — integrated with the 
Windows graphical features you want. 
Phar Lap FrontRunner is a powerful 
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your productivity 
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sized version of our DOS desktop for 
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FrontRunner’s powerful features... 
absolutely free! So call today and see 
how exciting a winning DOS desktop 
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Listing 1 stealth.asm 

; STEALTH.ASM 

Undef1ned_Init_0rder.. STEALTH ProtectAPI 

TITLE STEALTH VxD. steals requests from DOS device driver 


.386p ;allows prlviledged instructions 

VxD_IDATA_SEG ;start initialization data, discarded after 

.XLIST 

VxD_IDATA_ENDS ;end of initialization data, discard after 

INCLUDE VMM.Inc 


INCLUDE Debug.Inc 

VxD_DATA_SEG ;beginning of normal data 

INCLUDE Stealth.Inc 

VxD_DATA_ENDS ;end of normal data 

.LIST 



VxD_L0CKED_DATA_SEG ibeginning of page locked data 

; Virtual Device Declaration - Name, major, minor versions. 

■ 

; Control proc, ID, init order. V86 and protect API procs 

Next Int21 CS dd ? 


Next Int21 EIP dd ? 

Declare Virtual Device STEALTH. bMajorVer, bMinorVer, \ 

CurrentJM dd -1 

STEALTH.Control. STEALTH_Device_ID, \ 

Current_PSP dw -1 


Developers’ Toolkit Now Offered 


ISYS: The Editors’ Choice... 

For Text & Image Retrieval 

Leading computer publications consistently choose ISYS software as the preferred 
product in head-to-head reviews. They describe ISYS as the most user-friendly text- 
retrieval system available. Here’s what else they say: 

“ISYS for Windows is a winner!”. ..Infoworld “Hands-down winner!”... WordPerfect Magazine 

“ISYS... is a world-class package!”... PC Week “...the program to beat!”... PC Sources 

Now you can license the ISYS world-class engine tor your applications. We’ve spent 
more than five years developing and refining a host of powerful features... so you don’t 
have to reinvent the wheel. ISYS gives you full text and image search and retrieval 
capability with features like these for your Windows, DOS or Pen applications. 


• Researches 2 billion words in one 
second—chains databases 

• Fast, sub-second response on 
word or phrase searches 

• Interfaces to over 30 popular 
file formats, including all 
major word processors, ASCII 
ZIP, FoxPro and dBase 

• Very high level API 

• Automatically 
and transparently 
selects its own 
optimal retrieval 
strategy 

•Word, phrase, 

Boolean and 
proximity operators 

• Allows text access routines to 
be plugged into the bottom of 

the ISYS engine, providing full ISYS 
engine functionality for your own data 
sources, file formats—even distributed data 


Internally optimized, high-performance DLL 
•Wild cards and tense word stem searching 
•Searching within labelled paragraphs 
• Rule-based, or imperative-based, 
index building strategies 

• Progressive searching 

• Sounds-like searching 
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Very low disk overhead 
(typically 20-25% of 
original text size) 
• Designed for ease 
of use by the 
calling programmer 
•Searches up to 16 indexes 
at once—transparently 
• Builds an auxiliary index to 
the text in-situ—does not 
import text building strategies 
•Synonyms and dynamic synonyms 
• Ideal authoring software for CD-ROMs 
• Fast index building (typically 1 MB/minute) 
•Callable from C, Pascal, and even Visual Basic 


If you need powerful, full text and image search and retrieval capabilities, call and ask about 
the ISYS Developers’ Toolkit. You’ll be glad you did. 

Call 1-800-992-4797 

od 
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The end result of using a DOS de¬ 
vice driver in the Windows environ¬ 
ment is slow data transfers, in some 
cases, so slow as to be unusable. By 
writing a VxD that emulates the INT 
21h DOS device driver interface (see 
Table 1), you can avoid each of these 
performance bottlenecks, without 
changing any of the applications that 
access the device. An additional 
benefit is the fact that the 32-bit, flat- 
model code of VxDS can typically run 
much more efficiently than the 16- 
bit, real-mode code of DOS device 
drivers (due to increased instruction 
and data width and avoiding the use 
of segmented memory accesses). So, 
when applications make INT 21h calls 
to the original DOS device driver, my 
VxD intercepts the requests and 
simulates the action that a normal 
DOS device driver would perform - 
except much faster! 

Overview of 386 
Enhanced-Mode Windows 
and VxDs 

Enhanced-mode Windows runs on 
80386 or higher processors. The en¬ 
hanced-mode kernel (win386.exe) con¬ 
tains the virtual machine manager 
(VMM) and the standard virtual de¬ 
vice drivers (VxDs). The VMM uses 
the virtual 8086-mode (V86-mode) of 
the 80386 processor to create, run, 
manage, and terminate virtual ma¬ 
chines (VMs). V86 mode is a vari¬ 
ation of real mode. It provides for 
multiple 1Mb 8086 virtual machines 
within the 4Gb address space pro¬ 
vided by 32-bit protected mode. The 
VMM and VxDs run outside of the 
VMs at ring O, the highest privilege 
level in enhanced-mode Windows. 
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Table 1 Partial INT 21 h interface reference 

Interrupt 21 Function 

Parameters 

Returns 

Open file with handle 

AH = 3Dh 

AL = access, sharing mode 
DS:DX = pointer to filename 
to open 

AX = file handle of opened 
file if carry clear; error code if 
carry set. 

Close file with handle 

AH = 3 Eh 

BX = open file handle 

AX = error code if carry set; 
carry clear if successful. 

Read file or device 

AH = 3Fh 

BX = open file handle 

CX = number of bytes to read 
DS:DX = pointer to buffer to 
store data in 

AX = number of bytes read if 
carry clear; error code if carry 
set. 

Write file or device 

AH = 40h 

BX = open file handle 

CX = number of bytes to write 
DS:DX = pointer to data to 
write 

AX = number of bytes written 
if carry clear; error code if 
carry set. 


This gives VxDS nearly unrestricted 
access to the entire 4Gb address 
space. Windows applications, DLLs, 
and protected-mode DOS applications 
run at a lower privilege level (ring 3 
in Windows 3.1 and ring 1 in Win¬ 
dows 3.0). Real-mode DOS applica¬ 
tions also run at ring 3 in V86 mode. 

A VM (such as a DOS box) is like a 
simulated XT machine, an execution 
environment with its own address 
space, I/O ports, and interrupt vector 
table independent of any other VM 
currently running. The VMM uses the 
80386's virtual memory capability to 
map a single copy of the BIOS, DOS, 

DOS device drivers, and TSRs into 
each VM's address space. The first 
VM created (called the system VM) 
runs the Windows components and 
all other Windows applications in 
protected mode. Any DOS device 
drivers or TSRs that are resident before Windows starts 
will run in the system VM and will be mapped to the 
other VMs. DOS applications are V86-mode tasks and 
each runs in its own virtual machine, with its own mem¬ 
ory address space and CPU registers. Thus, DOS applica¬ 
tions running in V86 mode have the illusion of running 
on a PC with a 1 MB address space all to themselves. 


The VMM is responsible for allocating memory, manag¬ 
ing address pointers and handles, and managing commu¬ 
nication between applications and between an application 
and the hardware. The VMM manages multitasking by di¬ 
viding the CPU time, memory, and physical devices (key¬ 
board, display, ports, etc.) among the running VMs. Pro¬ 
grams are then multitasked by switching between VMs. 
The VMs run in a single-threaded, preemptive multitasking 
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even having to know its there, 
MemCheck is a potent weapon in all 
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minutes. You’ll pinpoint overwrites on 
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Listing 1 continued 


ALIGN DWORD 

Handle dw -1 

MaxRead dw -1 

DeviceName db "REGDEVNM",0 


VxD_LOCKED_DATA_ENDS ;end of page locked data 

VxD_ICODE_SEG ;start of initialization code, discarded 


; STEALTH_DeviceInit - called at system boot,do init tasks 
; ENTRY: EBX = Sys VM handle. EXIT: clc/stc to load/abort 
.-** 

BeginProc STEALTH_DeviceIn1t 

;do the Virtual-86 mode hook of Int 21h 
mov eax, 21h 

mov esi, 0FFSET32 $TEALTH_V86_Int21Handler 

VMMCall Hook_V86_Int_Chain 

;save protected-mode vector for int 21h 
mov eax, 21h 

VMMcall Get_PM_Int_Vector 
mov [Next_Int21_CS], ecx 
mov [Next_Int21_EIP], edx 

;do the protected-mode hook of Int 21h 
mov esi. 0FFSET32 STEALTH_PM_Int21Handler 

xor edx, edx 

VMMcall A11ocate_PM_Call_Back 
jc SHORT AbortLoad 

movzx edx, ax 

mov ecx, eax 

shr ecx, 16 

mov eax, 21h 

VMMcall Set_PM_Int_Vector 

clc ;no error - load VxD 

ret 

AbortLoad: ;jump here if conditions warrant not loading 


stc ;fail load 

ret 

EndProc STEALTH_DeviceInit 

VxD_ICODE_ENDS ;end of initialization code, discarded 
VxD_CODE_SEG ;beginning of standard code segment 


: STEALTH_ProtectAPI - main dispatch routine for PM apps 
; EAX: API id to execute, jump to corresponding routine. 

;.** 

BeginProc STEALTH_ProtectAPI, Public 

cmp [ebp].Client_AX, MAX_PROTECT_APIS 

jg SHORT Unknown_API 

cmp [ebp].Client_AX, PROTECT_API_VERSION 

je short ApiVersion 

;implement open, write, read, close, enable, disable 
jmp short Unknown_API 

ApiVersion: 

mov [ebp].Client_Flags, 0 

mov [ebp].Client_AX, wVersion 

mov ax. MaxRead 

mov [ebp].Client_BX, ax 

ret 

Unknown_API: 

mov [ebp].Client_Flags, CF_Mask 

ret 

EndProc STEALTH_ProtectAPI 


STEALTH_Serv_Version - VxD service, called by other VxDs 


BeginProc STEALTH_Serv_Version, Service 
mov eax, wVersion 
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environment - DOS applications can be preempted in or¬ 
der to allow other DOS or Windows applications to exe¬ 
cute. In other words, VMs offer preemptive multitasking. 
Unfortunately, since all Windows applications run in a sin¬ 
gle VM (the system VM), although a DOS box can preempt 
the currently running Windows application, one Windows 
application cannot preempt another Windows application. 
Thus, some Windows applications (such as Visual C++) 
find it useful to spawn a hidden DOS box to perform com¬ 
putation-intensive tasks (such as compilation) in order to 
gain the benefits of preemptive VM multitasking. 

VxDS are 32-bit, flat-model DLLs. 

However, the executable file format 
of a VxD is very different from that 
of a standard DLL in Windows 3.x, so 


Listing 1 continued 


movzx ebx, MaxRead 

clc 

ret 

EndProc STEALTH_Serv_Version 


VxD.COOEjNDS ;end of 

standard code segment 

VxDJ.OCKED_CODE_SEG beginning of page locked code 






Table 2 VxD services 
unavailable in Windows 3.0. The 
following services require Windows 
3.1. They should be avoided in 
your VxD if you wish for it to 
operate in Windows 3.0. 


_AddFreePhysPage 

_PageResetHandlePAddr 

_SetLastV86Page 

_GetLastV86Page 

JVIapFreePhysReg 

JJnmapFreePhysReg 

XchgFreePhysReg 

_SetFreePhysRegCalBk 

Get_Next_Arena 

Get_Name_Of_Ugly_TSR 

Get_Debug_Options 

Set_PhysicaI_HMA_Alias 

_GetGlblRngOV86IntBase 

_Add_Global_V86_Data_Area 

GetSetDetailedVMError 

ls_Debug_Chr 

Clear_Mono_Screen 

Out_Mono_Chr 

Out_Mono_String 

Set_Mono_Cur_Pos 

Get_Mono_Cur_Pos 

Get_Mono_Chr 

Locate_Byte_ln_ROM 

Hook_lnvalid_Page_Fault 

Unhook_lnvalid_Page_Fault 

Set_Deiete_On_Exit_File 

C!ose_VM 

Enable_Touch_1 st_Meg 
Disable_Touch_1 st_Meg 
Install_Exception_Handler 
Remove_Exception_HandIer 
Get_Crit_Status_No_Block 



Quadbase-SQL is a fast, full-featured, scalable, industrial-strength SQL relational 
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VxDS cannot be loaded by applications. VxDS manage sys¬ 
tem resources, typically a hardware device (such as the 
programmable interrupt controller, the keyboard, the dis¬ 
play, and the serial and parallel ports) or an installed soft¬ 
ware component. Since multiple VMs can be running at 


the same time, each potentially attempting to access the 
same resource, VxDS arbitrate multiple accesses to the 
same device, giving applications the illusion that they 
have sole access to the hardware device. VxDS can also 
provide services to the enhanced-mode Windows system 


Listing 1 continued 


; STEALTH_Control - handles messages. Must be LOCKED. 

; ENTRY: EAX = Message number, EBX = VM Handle 
.** 

BeginProc STEALTH_Control 

Control_Dispatch Devicejnit, STEALTH_DeviceInit 

clc 

ret 

EndProc STEALTH_Control 


; STEALTH _V86_Int21Handler - V86 interrupt 21 handler 
; EXIT: Clear carry flag to prevent system from passing 
; interrupt to next hook, Set carry to pass it on. 
.** 

BeginProc STEALTH_V86_Int21Handler 


cmp 

[ebp.Client_AH], 3Dh 

;DOS open commmand? 

je 

SHORT DosOpen 


:if not handle to my device, 

don’t need to continue 

mov 

bx, Handle 


cmp 

[ebp.Client BX], bx 


jne 

SHORT V86_Pass0n 


cmp 

[ebp.Client AH], 3Eh 

;DOS close command? 

je 

SHORT DosClose 


jmp 

SHORT V86_Pass0n 

;Just pass others on 

DosClose: 

call 

CompareCurrentTask 

;check if same task 

cmp 

ecx. TRUE 

;Is is same PSP and VM? 

jne 

SHORT V86_Pass0n 

;No - so pass on. 
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mov 

Handle, -1 

;Yes - so reset values 

mov 

Current_VM. -1 


mov 

Current PSP. -1 


jmp 

SHORT V86_Pass0n 

;then pass on. 

DosOpen: 



mov 

ax, (Client.DS SHL 8) + Client.DX 


VMMcall Map_Flat filename string in eax 

:compare filename with device driver name 
cld ;forward compare 

mov ecx, SIZE DeviceName 

mov esi, 0FFSET32 DeviceName 

mov edi, eax 

repe cmpsb 

jnz SHORT V86_Pass0n ;not device driver name 
;String matched, set callback on completion, pass on. 
xor eax, eax ;timeout in milliseconds 

xor edx, edx ;reference data ptr 

mov esi, 0FFSET32 STEALTH_OpenReturn ;call back 

VMMCall Call_When_VM_Returns 

stc ;pass interrupt to next hook 

ret 

V86_Pass0n: 

stc ;set carry flag, pass interrupt to next hook 

ret 

V86_DontPass0n: 

clc ;clear carry indicates success, don't pass on 

ret 

EndProc STEALTHJ86_Int21Handler 

.** . 

; STEALTH_PM_Int21Handler - Protect mode int 21 handler 
: EXIT: Simulated far jump to pass on, else simulate iret 

; . . . ★★ 

BeginProc STEALTH_PM_Int21Handler 

;if no handle open now, then don’t need to continue 


cmp 

Handle. -1 


je 

SHORT PM.PassOn 


:if not handle to my device. 

don’t need to continue 

mov 

bx. Handle 


cmp 

[ebp.Client_BX], bx 


jne 

SHORT PM_PassOn 


cmp 

[ebp.Client AH], 3Fh 

;DOS read command? 

je 

SHORT DosRead 


cmp 

[ebp.Client_AH], 40h 

;DOS write command? 

je 

SHORT DosWrite 


jmp 

SHORT PM_PassOn 

;not interested. 

DosRead: 



call 

CompareCurrentTask 

iCompare task info 

cmp 

ecx, TRUE 

;Is is same PSP and VM? 

jne 

SHORT PM.PassOn 

;No. 

mov 

ax. (Client.DS SHL 8) + Client_DX 

VMMcall 

Map_Fl at 

ibuffer address in EAX 

movzx 

ecx, [ebp.Client_CX] 

ibuffer length in ECX 

mov 

MaxRead, cx 

;Save read size request 

call 

StealthRead 

:StealthRead sets count 

mov 

[ebp.Client_AX], ax 

;DOS expects count in ax 

jmp 

SHORT PM_DontPassOn 

;no one else reads 1 

DosWrite: 



call 

CompareCurrentTask 

iCompare task info 

cmp 

ecx. TRUE 

;Is is same PSP and VM? 

jne 

SHORT PM_PassOn 

;No. 

mov 

ax, (Client_DS SHL 8) + Client_DX 

VMMcall 

Map_Fl at 

ibuffer address in EAX 

movzx 

ecx, [ebp.Client_CX] 

;buffer length in ECX 

call 

StealthWrite 

.•StealthWrite sets count 

mov 

[ebp.Client AX], ax 

;DOS expects count in ax 

jmp 

SHORT PM_DontPassOn 

;no one else writes! 


PM_PassOn: 

mov ecx, [Next_Int21_CS] 
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(such as memory management, scheduling, interprocess 
communications, and hooking events and interrupts), to 
other VxDS, to the VMM, and to applications. 

Hooking Interrupts 

Interrupt reflection and processing is fairly complex in 
enhanced-mode Windows. Since Windows applications 
run at ring 3 (the least privileged mode of the 80386), 
Windows must reflect the interrupts from the 32-bit Win¬ 
dows kernel into the appropriate VMs. But before the VM 
can run, its execution priority must be raised and then it 
must wait for the active time slice to finish before it can 
execute. As you might expect, this whole process slows 
down interrupt handling. Windows 
applications can avoid this by calling 
directly (via protected-mode APIs) or 
indirectly (via software interrupt 
hooks) into a VxD rather than a DOS 
device driver. 

These are the basic steps the 
VMM takes to process a software in¬ 
terrupt: 

• An application in a particular VM 
performs, for example, a file op¬ 
eration that executes a software 
interrupt. 

• The processor transitions to ring 0 
and calls the appropriate VMM in¬ 
terrupt handler. 

• The VMM interrupt handler dis¬ 
patches the interrupt by calling 
any protected-mode callback rou¬ 
tines installed for that interrupt. 

• The protected-mode callback pro¬ 
cedure can choose to process or 
ignore the interrupt, then returns 
using the RET instruction. 

• Control then returns to the VMM 
handler. The VMM checks for any 
outstanding events, and calls the 
appropriate event callback proce¬ 
dures. 

• If the interrupt was not processed 
by any callback procedures, the 
VMM handler reflects the interrupt 
back into the VM so that the V86- 
mode handler has an opportunity 
to process it. 

• Finally, the VMM executes the 
IRET instruction. The processor 
transitions back to the calling 
VM's privilege level and returns 
control to the calling application. 

Creating the Stealth VxD 

The first step in creating a VxD 
is to give it a name and an ID. 

You can pick the name yourself, 
but you might be surprised to 
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mov edx, [Next_Int21_EIP] 
VMMjmp Simulate_Far_Jmp 
ret 

PM_DontPassOn: 

VMMcall Simulatejret 
ret 

EndProc STEALTH_PM_Int21Handl er 


;Chain to next vector. 


;Eat the interrupt. 


STEALTH_OpenReturn - On return from open command, save 
file handle, current PSP segment, current VM handle. 


BeginProc STEALTH_OpenReturn 

jclient’s carry flag indicates if file open succeeded 
test [ebp.Client_EFLAGS], CF_Mask ;Success? 
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... that you might even'^vant to 
use it as a hypertext authoring 
tool, independent of providing 
help for a product. Certainly for 
Windows programmers it’s 
indispensable."! - July 1993 
Toolkits section 

Windows Magazine gave the 
Help Magician an "A" for 
creating help files interactively. 


Create, edit, and test help quickly 
in an integrated environment! 

Some original features 

□ Built-in full-featured editor 

□ Create jumps and popups 

□ Create multiple hot spots 

□ Include bitmaps 

□ Create bulleted or numbered lists 

□ Create browse sequences 

□ Use various font styles and colors 

□ Test help files instantly 

□ Quickly writes RTF files 

□ Imports MS Word and 
Lotus Ami Pro RTF files 

□ Extensive error & syntax checking 

□ Works with any Windows language 
including Visual BASIC and C 

□ Use standard WinHelp engine 

Years in development, the Help Magician has more experience, features, 
and automation based on customer response than any other help 
authoring tool. An external word processor is not necessary and tech 
support is always free! SITE and Network licensing available. 


Some version 2.5 features 

□ No memory limitations 

□ Secondary windows 

□ Non-scrolling regions 

□ Set background colors 

□ Advanced paragraph 
formatting 

□ Full macro support 

□ Jump to other help files 

□ Multiple file support 

□ Help window sizing 

□ Built-in spell checker 

□ Writes #define files 

□ Plays Video for Windows, 
.wav, & .mmm movie files 
using WinHelp engine 
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know that Microsoft does not encourage developers to 
use the 'VxxxxxxD.386' naming convention for third-party 
VxDS. That convention is generally reserved for VxDS that 
are part of the Windows 3.x shipping product, such as the 


VCD (Virtual COM Device). Instead, Microsoft just recom¬ 
mends using as descriptive a name as possible - prefer¬ 
ably, one that embeds your company name - to reduce 
the chance of two VxDS having the same name. Since my 


Listing 1 continued 


jnz 

SHORT OpenFailed 

: No. 

pushad 


;save VxD’s registers 

VMMCall 

Get_Cur_VM_Handle 

;EBX=current VM handle 

mov 

Current_VM, ebx 

:Save VM of this task 

call 

GetCurrentPSP 

;EBX=current PSP 

mov 

Current_PSP. bx 

;Save PSP of this task 

mov 

ax, [ebp.Client_AX] 

[client’s AX=file handle 

mov 

Handle, ax 

;save the file handle 

popad 


[restore VxD’s registers 

OpenFailed 

ret 




EndProc STEALTH_OpenReturn 


CompareCurrentTask - Compare current VM and PSP with the 
VM and PSP of the task that opened the device. 

EXIT: ECX = TRUE if match. FALSE is no match. 

.. ** 


BeginProc CompareCurrentTask 
pushad 

VMMCall Get_Cur_VM_Handle 
cmp ebx, Current_VM 

jne SHORT NoMatch 

call GetCurrentPSP 

cmp bx. Current_PSP 

jne SHORT NoMatch 

popad 

mov ecx, TRUE 

ret 


:save VxD’s registers 
;EBX=current VM handle 
[Same VM that opened device? 
;No. 

;EBX=current PSP 

;Same PSP that opened device? 

;No. 

;restore VxD’s registers 
[Same task! 
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NoMatch: 

popad [restore VxD's registers 

mov ecx, FALSE ;Different task! 

ret 

EndProc CompareCurrentTask 


GetCurrentPSP - Get PSP of the currently executing task. 
EXIT: EBX = PSP of current task. 


BeginProc GetCurrentPSP 

Push_Client_State ;save current VM’s state 

VMMCall Begin_Nest_Exec ;begin nested execution 

mov [ebp.Client_AH], 62h ;Client_AH = funct (Get PSP) 

mov eax, 21h ;EAX = interrupt number 

VMMCall Execjnt icurrent VM calls MS-DOS 

VMMCall End_Nest_Exec ;end nested execution 

:Int 21 function 62 (Get PSP) returns the PSP segment 
movzx ebx, [ebp.Client_BX] ;PSP segment in client BX 

Pop_Client_State ;restore current VM’s state 

ret 

EndProc GetCurrentPSP 


StealthRead - read using your own custom I/O protocol. 
ENTRY: EAX = data. ECX = length. EXIT: EAX = length. 


BeginProc StealthRead 

Trace_0ut "Do a real READ already!" 

mov eax, ecx ;caller expects count in EAX 

ret 

ReadError: ;1f error reading, jump here 

mov eax, D0S_ERR0R_READ ;DOS read error 

mov [ebp.Client_Flags], CF_Mask [error. set carry 

ret 

EndProc StealthRead 


: StealthWrite - write using your own custom I/O protocol. 

; ENTRY: EAX = data, ECX = length. EXIT: EAX = length. 

;. -. ** 

BeginProc StealthWrite 

Trace_0ut "Do a real WRITE already!" 

mov eax. ecx :caller expects count in EAX 

ret 

WriteError: ;if error reading, jump here 

mov eax, D0S_ERR0R_WRITE ;D0S write error 

mov [ebp.Client_Flags], CF_Mask ;error, set carry 

ret 

EndProc StealthWrite 


VxD_LOCKED_CODE_ENDS ;end of page locked code 

VxD_REAL_INIT_SEG :Real Mode Initialization code 


: STEALTH_Real_Init - Real mode init. Check duplicate load 

; ENTRY: 

AX = VMM Version. BX = 

Load Flags. 

BeginProc 

STEALTH_Real Init 


test 

bx. Duplicate_Device ID [Already loaded? 

Jnz 

SHORT duplicate 

;Yes. 

xor 

bx. bx 

[exclusion table (no) 

xor 

si, si 

[instance data table (no) 

xor 

edx, edx 

[reference data (no) 

mov 

ax. Device Load Ok 

[successful load 

ret 



duplicate 


[abort without message 

mov 

ax. Abort Device Load + No Fail Message 

ret 



EndProc STEALTH_Real_Init 


VxD_REAL_INIT_ENDS :end of Real Mode Initialization Code 


END 

: End of File 
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VxD secretly steals requests away from a DOS device 
driver (and is not representative of any company!), I sim¬ 
ply named it 'Stealth.' 

If your VxD doesn't provide any services or custom 
APIs (either V86-mode or protected-mode), you can use 
Undefined_Device_ID as the ID for your VxD. Even in this 
case, however, you might still consider using a unique ID, 
since the normal convention for preventing a VxD from 
loading twice is based on unique device IDs. If you decide 
to provide services or APIs, or want to prevent your VxD 
from loading twice, you'll need a unique ID that only Mi¬ 
crosoft can assign. IDs in the range of 0000/7 - 01FFh are 
reserved for Microsoft's own internal VxDS which are con¬ 
tained in win386.exe. I used a fictitious ID (299%) for the 
Stealth VxD; please don't use it for your VxD as there's a 
chance it belongs to someone! You can request a unique 
ID from Microsoft by sending email to: 

vxdid@microsoft.com 

If you just send a short note to this address, you will auto¬ 
matically receive via return mail a request form to fill out 
and return (see Paul Bonneau's article, 'A VxD to Interrupt 
DOS Output' in this issue for a sample form). Alternatively, 
you can obtain the correct form from article Q84000 in 
Microsoft's KnowledgeBase on CompuServe (also available 
on the MSDN CD-ROM). In either case, fill out the form 
and email it back to the address just mentioned. 


Listing 2 stealth, inc 


; STEALTH.INC 


;**. VxD ID and Version numbers .** 

STEALTH_Dev1ce_ID equ 2999H ;Get from Microsoft!! 

bMajorVer equ 01 

bMinorVer equ 00 

wVersion equ (bMajorVer * 256 + bMinorVer) 


;**. VxD Service Table- 

Begin_Service_Table STEALTH 

STEALTH_Service STEALTH_$erv_Version 
End_Service_Table STEALTH 


;**. VxD Protected API .* 

PROTECT_API_VERSION equ 0 ;add protected-mode APIs 

MAX_PROTECT_APIS equ 1 ;while you’re at it! 


. ** 

DOS_ERROR_ACCESS 

DOS_ERROR_HANDLE 

D0S_ERR0R_WRITE 

D0$_ERR0R_READ 


DOS Error Codes 
equ 05h 
equ 06h 
equ lDh 
equ lEh 


★★ 


05d 

06d 

29d 

30d 


stealth.asm (Listing 1) and stealth, inc (Listing 2) contain 
the source file and include file for the Stealth VxD. All 
VxDs must have a 'virtual device declaration' and they 
must declare a name, version number, control procedure, 
and initialization order. They can optionally declare a de¬ 
vice ID and V86 and protected-mode API procedures. The 
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Listing 3 stealth.def 

LIBRARY 

STEALTH 

DESCRIPTION 'Stealth Windows 3.x VxD' 

STUB 

'WINSTUB.EXE' 

EXETYPE 

DEV386 

SEGMENTS 


LTEXT 

PRELOAD NONDISCARDABLE 

LDATA 

PRELOAD NONDISCARDABLE 

ITEXT 

CLASS TCODE’ DISCARDABLE 

IDATA 

CLASS 'ICODE’ DISCARDABLE 

TEXT 

CLASS 'PCODE’ NONDISCARDABLE 

_DATA 

CLASS ’PCODE' NONDISCARDABLE 

EXPORTS 


STEALTH_DDB @1 ;VxD name plus _DDB, must be @1 


Stealth VxD uses the Declare_Virtual_Device macro to de¬ 
clare its virtual device information. This macro creates a 
device descriptor block (DDB) with the name of the VxD 
appended with _DDB (STEALTH_DDB in my case). This DDB la¬ 
bel must be explicitly exported in the module definition 
file for the VxD. The DDB provides enough information to 
allow the VMM to initialize the VxD, send control mes¬ 
sages to it, and manage its communication with applica¬ 
tions. 

For the initialization order field, use either Undefined_De- 
vice_ID or your assigned ID. The initialization order deter¬ 
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mines when the VMM initializes the VxD. VxDS with lower 
values are initialized before those with higher values. If 
two VxDS have the same initialization order value then 
they are initialized in the order they occur in the sys¬ 
tem. ini file. If you want your VxD to load just before or 
after a standard VxD, you can add or subtract a small 
amount from that VxD's predefined initialization order, as 
defined in vmm.inc (e.g., DOSMGRJnit_Order + I). 

I specified STEALTH_Control as my control procedure. The 
VMM communicates with my VxD by sending messages 
to this control procedure. You can easily specify which 
messages to process by using the Control_Dispatch macro. 
I chose to process only the Devicejnit message, which is 
sent during system boot. When the Devicejnit message is 
sent, I call my STEALTH_DeviceInit procedure so that I can 
hook INT 21h during initialization. A control procedure is 
required, even if it doesn't process any messages, and it 
must reside in the locked code segment, lxD_L0CKED_C0DE. 

STEALTH_DeviceInit resides in the VxDJCODE segment and 
is discarded after initialization. In STEALTH_DeviceInit, I 
hook both the V86-mode and protected-mode INT 21h 
vectors. If only the V86-mode interrupt is hooked, the 
Stealth VxD functions fine except for one small detail - 
the requests are still broken into 8Kb buffers before 
STEALTH_V86_Int21Handler is called. This is because DOSMGR 
is getting the interrupt before my V86-mode handler. To 
get a shot at this interrupt before DOSMGR, I also had to 
install a protected-mode handler, STEALTH_PM_Int21Handler, 
after DOSMGR's handler. Since DOSMGR installs its pro¬ 
tected-mode handler during the Sys_Critical_Init mes¬ 
sage, I can install my handler during the Devicejnit, 
which is sent after Sys_CriticalJnit. Alternatively, as long 
as my VxD is loaded after DOSMGR, i can install the han¬ 
dler during the SysJCriticalJnit message, which will en¬ 
sure that my handler will be installed after DOSMGR's 
handler. By using an initialization order that is greater 
than the order DOSMGR uses (such as D0SMGRJnit_0rder + 
1) I can guarantee that my VxD will load after DOSMGR 
loads. The UndefinedJnit_Order is larger than 
DOSMGRJnit_Order, so it can also be used. If, for any reason, 
you wish to prevent your VxD from loading during initiali¬ 
zation, simply set the carry flag before returning from the 
initialization routine. 

The mechanisms for installing the two types of hooks 
are quite different. For the V86-mode handler, you simply 
specify the interrupt vector and the handler routine and 
call the Hook_V86Jnt_Chain VMM service. By contrast, in¬ 
stalling a protected-mode handler is a bit more similar to 
installing a DOS ISR (interrupt service request). First, re¬ 
trieve the current INT 21h vector and save the returned 
address (GetJMJnt_Vector). Then allocate a protected- 
mode callback for your handler routine (Allo- 
cate_PM_Call_Back) and install it as your INT 21h handler 
( Set_PMJnt_Vector ). 

A VxD can provide direct communication with a pro¬ 
tected-mode application via the protected-mode API entry 
point. The STEALTH_ProtectAPI routine (specified in the De- 
clare_Virtual_Device statement) currently provides only the 
standard "get version' function, which is, by convention, 
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function number 0. The function number, again by con¬ 
vention, is specified in the client's AX register. As with all 
other VxD entry points, the client's registers are passed in 
EBP as a Client_Reg_Struc. I also return the last read re¬ 
quest length in BX as a debugging variable, so that you 
can easily check if the interrupts are successfully bypass¬ 
ing the efforts of DOSMGR. Adding other functions to the 
STEALTH_ProtectAPI routine is fairly simple. You could also 
add a V86-mode API routine. In fact, with a little care, you 
can use one routine to support both the protected-mode 
and V86-mode API entry points. The VMM calls the appro¬ 
priate entry point based on the mode of the calling appli¬ 
cation. 

Although STEALTH_Serv_lersion does basically the same 
things as STEALTH_ProtectAPI, it is implemented as a service. 
Services are intended to be called by other VxDS. They are 
not exported, as they would be in a normal DLL, but in¬ 
stead use a dynamic linking mechanism via I NT 20h. I de¬ 
clare my service table in the stealth, inc file by using the 
Begin_Service_Table/End_Service_Table macro pair. The serv¬ 
ice procedure contains the Service option in the BeginProc 
macro. If the service procedure is not located in the 
VxD_C0DE segment, you must explicitly define the segment 
name in the service table. If you declare a service table, 


the first service must be the 'get version' service, which is 
used by VxDS to check for the presence of other VxDS. It 
should set the version number in AX and clear the carry 
flag. To call services from other VxDs, include the file that 
contains the service table declaration for that VxD. For ex¬ 
ample, to use services of the VMM, include the vmn. inc file 
and use the VMMcall macro. Use the VxDcall macro for 
other VxDS. 

To access the device that this VxD is handling, the call¬ 
ing application will open some reserved filename. The file 
open and close commands must be reflected all the way 
through to DOS in order for the file handle to be properly 
allocated and deallocated. Also, in the case of the open 
command, I need to get control at the very end of the 
interrupt vector chain, after the DOS code has had a 
chance to allocate the file handle. For this reason, I must 
process the file open and close commands in the V86- 
mode interrupt handler (STEALTH_V86Jnt21Handler). 

In order to associate file I/O requests with a particular 
device, I must save the file handle and then compare this 
file handle with the handle for any subsequent read, write, 
or close commands. In the case of the open command, I 
compare the filename being opened with the name of the 
DOS device driver that I am virtualizing ('REGDEVNM'). By 


PSPs and File Handles 


Each instance of a Windows application is a task 
and is identified by a task handle as well as an in¬ 
stance handle. Since DLLs aren't instanced, they are 
not tasks and thus don't have task handles or stacks. 
The task handle is actually a handle to a task data¬ 
base (TDB) structure. The TDB contains, among other 
things, the module handle, instance handle, and the 
PSP (Program Segment Prefix; also called the PDB, or 
program database, in Windows). 

A PSP is a 256-byte block of memory allocated by 
the system on behalf of any running DOS or Windows 
program. The PSP is followed immediately by the pro¬ 
gram's code and data. In the case of Windows applica¬ 
tions, it's the kernel's job to create a unique DOS PSP 
for each Windows application that is executed. The 
Windows scheduler sets the PSP for the current task 
whenever a task switch occurs. The main purpose of 
the PSP is to contain all the information necessary to 
load, execute, and terminate a process. The segment 
address of the PSP is used to identify each resident 
(whether active or not) process; it is referred to as the 
process ID or PID. 

The PSP includes, among many other things (some 
of which are purely historical now), the list of handles 
the process uses to identify its files and devices. Since 
DOS file handles are associated with a PSP and a PSP 
corresponds to the current process, file handles cannot 
be shared among applications. Since the TDB contains 


a reference to the PSP, open file handles are stored in 
the TDB. And, since DLLs don't have TDBs, any file 
handles they open are stored in the TDB of the calling 
application. For two programs to access the same file 
handle, they must be using the same PSP. 

For example, when a process issues an Int 21h, 
function 3Dh request to open a file, the handle returned 
is an index into the file table of the current PSP. This 
PSP is not necessarily the PSP of the process that is¬ 
sued the Int 21h. For instance, if an interrupt handler 
issued the Int 21h, it will be operating on the PSP of 
the foreground process, not the PSP of the process 
containing the interrupt handler. Whenever a process 
switch occurs, the current PSP must also be switched if 
any file I/O is to be performed. Otherwise, you will be 
accessing the files or devices of the old foreground 
process rather than your own files or devices. Also re¬ 
member that when a process terminates, all its open 
files are closed and its file handles become invalid. 

You can use these fully reentrant DOS services to 
get and set the PSP. Function 62h is documented under 
DOS 3.x and above and does not require using the 
critical-error stack. In each case, BX is used to set or 
retrieve the PSP Address. 

Interrupt 21 h, Function 50h - Set PSP Address 
Interrupt 21 h, Function 51h - Get PSP Address 
Interrupt 21 h, Function 62h - Get PSP Address □ 
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passing the interrupt on and setting a callback on comple¬ 
tion event, I cause DOS to allocate a file handle and I 
have a chance to save the handle before the interrupt 
returns. This means that the DOS device driver must be 
installed (or a file with the same name must exist) so that 
the open command can allocate a file handle for it. This is 
probably not an unreasonable request. By installing both 
a DOS device driver and a VxD, you are covered for both 
standard and enhanced-mode operation, and you can 
choose to let some of the less time-critical operations, 
such as lOCTLs, pass on to the DOS device driver and thus 
not worry about them in the VxD. 

Since file handles are only unique within the context of 
a PSP and PSPs are only unique within the context of a 
specific VM, all three values (the file handle, VM handle, 
and current PSP) must be saved when the device is 
opened, and then compared for each subsequent read, 
write, and close command to determine if it is a request 
for the same device driver. See the sidebar, 'PSPs and File 
Handles,' for more information. 

The device read and device write commands must be 
handled in the protected-mode interrupt handler 
( STEALTH_PM_Int21Handler ) because I must process them be¬ 
fore DOSMGR does (in order to avoid the breaking up of 
I/O buffers). Unfortunately, this means that even though I 
can process open and close commands from both V86- 
mode and protected-mode applications, only protected- 
mode applications will bypass the DOSMGR and receive 
the full extent of the performance enhancement. I simply 


Figure 1 teste 


int (far *vxdproc)(int); 
int iVerslon, iMaxRead; 

/* Get the address of the VxD’s API entry-point */ 

_asm { 
push di 
push es 

mov ax, 1684h 

mov bx, 2999h ;id for STEALTH VxD 

xor di, di 
mov es, di 
int 2Fh 

mov word ptr vxdproc, di 
mov word ptr vxdproc+2, es 
pop es 
pop di 

} 

/* if vxdproc is zero, then no STEALTH VxD installed */ 
if (vxdproc == 0) return FALSE; 

/* now call the version number entry-point */ 

_asm { 
push di 
push es 
mov ax, 0 
call vxdproc 

mov iVersion, ax ;save version number 

mov iHaxRead, bx ;save last max read 

pop es 
pop di 

} 


call StealthRead or StealthUrite if it is a read or write re¬ 
quest to my device. 

Call the Simulated RET service to consume the protected- 
mode interrupt. To chain to the next INT 21h handler, call 
the Simulate_Far_Jnip service, specifying the previous inter¬ 
rupt vector address that was saved during initialization. Al¬ 
ways return with a normal RET instruction so that the 
VMM can perform the IRET when it is done. 

Both STEALTH_V86_Int21Handler and STEALTH_PM_Int21Han- 
dler are placed in the VxD_L0CKED_C0DE segment, as well as 
any routines they call. By keeping this code in locked seg¬ 
ments, you avoid the chance of the segment being paged 
out in enhanced-mode Windows. 

STEALTH_OpenReturn is the callback routine that I register 
to be called when the VMM executes an IRET to return 
from processing the INT 21h open command. This is where 
I save the file handle, current VM handle, and the current 
PSP. 

To get the current PSP requires issuing an INT 21h, func¬ 
tion 62h. Each VM has a copy of DOS running in it which 
contains the code for handling INT 21h. I need to have the 
current VM execute this DOS code rather than the code it 
was executing (the client's CS:(E)IP) before my Stealth VxD 
began executing. Before calling code in the current VM, 
you must save the client state information so that the VM 
registers aren't changed when the VxD ultimately returns 
back to the VM. You can use the Save_Client_State/Re- 
store_Client_State services or the Push_Cli- 
ent_State/Pop_Client_State macros to accomplish this. I pre¬ 
fer the macros since they save information on the stack 
rather than in static data and are thus safe for reentrancy. 
Also, since executing code in the VM can always result in 
a VMM service being called, the VMM must be prepared 
for reentrancy. The Begin_Nest_Exec service only returns 
when the VMM can be safely re-entered. It also manages 
the client CS:(E)IP so that when the VxD ultimately returns 
back to the VM, the VM can begin executing where it left 
off. From within this nested execution block, you can call 
the Execjnt service to execute an INT 21h, function 62h 
into the current VM. Call End_Nest_Exec to end the nested 
execution block. 

StealthRead and StealthUrite are just stub routines that 
return the amount requested as the amount actually read 
or written by the device. Insert your own read and write 
code for the interface you support (such as SCSI, serial, 
Bitronics, etc.). The client buffer address passed during 
read and write commands is either a segmentioffset or 
selector:offset address. I use the Map_Flat service to con¬ 
vert either of these addressing modes to a 32-bit linear 
address usable by my VxD. 

Finally, the STEALTH_Real_Init routine contains my real¬ 
mode initialization code. But, since this routine is not 
specified anywhere else in the code, how does the VMM 
know that this is my real- mode initialization code? Simply 
by virtue of the fact that it resides in the VxD_REAL_INIT 
segment - the VM assumes the routine at offset 0 in this 
segment is the real-mode initialization code. This is a 
chance for my VxD to perform any required initialization 
tasks before Windows switches to protected mode. I also 
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check the load flag in the BX register to determine if I've 
already been loaded (only if my VxD has a unique ID) and 
if so fail loading. You may fail with or without displaying 
a message. This code is discarded after the real-mode in¬ 
itialization is complete. 

Optimizing the Stealth VxD 

Since the goal of this VxD is improved performance, it 
might be good to review some very basic optimization 
tips. 

Remember that most of the code in the VxD is trig¬ 
gered off an INT 21h. INT 21h is still a major highway in 
Windows, so if you sit on the interrupt for too long before 
passing it on, you'll affect the performance of the entire 
system whenever an application does file I/O operations! 

There are experts who could squeeze out every last 
wasted execution cycle from your code. But the wide vari¬ 
ety of available system configurations and memory archi¬ 
tectures using 386 and 486 processors makes optimizing 
at the instruction level a painstaking (and sometimes fu¬ 
tile) process. For my purposes, practicing a few basic opti¬ 
mization guidelines is sufficient - but please feel free to 
count all the clock cycles you like. 

The 386 processor can execute instructions relatively 
faster than it can fetch them, so performance is often 
bound by the prefetch queue. There are several tech¬ 
niques for minimizing this dependency. Use short instruc¬ 
tions whenever possible; there are less bytes to fetch. 
Avoid branching; it causes the prefetch queue to be emp¬ 
tied before the branch. 

Remember that you are guaranteed to have at least a 
386 processor, so don't be afraid to use the more com¬ 
plex math and repeat-string functions. They are very effi¬ 
cient and eliminate the prefetching instructions and 
branching you might have used in your own versions of 
these operations. 

Although memory access time is greatly improved on 
386 processors as compared to the early x86 processors, 
it usually still pays off to use registers as much as possible. 
And when using the registers in a VxD, it is often more 
efficient to use the full 32-bit versions (i.e., EAX rather than 
AX). Since VxDS execute their code in 32-bit code seg¬ 
ments, the CPU assumes a default operand size of 32 bits. 
Using 16-bit registers in instructions requires the additional 
operand size override prefix in the resulting opcode, which 
increases instruction size (a 2-byte MOV instruction increases 
to three bytes, a 50 percent increase in instruction size) 
and requires an occasional fetch of the operand size over¬ 
ride value. 

Whenever possible, use doubleword alignment for dou¬ 
bleword-sized memory accessing and word alignment for 
word-sized memory accessing. Obviously, crossing these 
boundaries requires an extra memory access. You may 
also want to doubleword-align branch points in very tight 
loops of code. I used the ALIGN DUORD assembler directive 
before some of the byte- and word-sized variables in 
stealth.asm (Listing 1). You can also use the Dword_Align 
macro to align the next instruction on a DUORD boundary. 


Building the Stealth VxD 

VxDS require a module definition file, much like a DLL. 
The module definition file for the Stealth VxD is in 
stealth.def (Listing 3). The predefined VxD segments are 
listed in the SEGMENTS section. The LIBRARY entry must spec¬ 
ify the name of the VxD. The DDB is the only export your 
VxD should require; it must be the name of the VxD ap¬ 
pended by _DDB (STEALTH_DDB in my case) and it must be 
ordinal value 1. 

I used the Microsoft 3.1 DDK to build my VxD. As long 
as you avoid a few services (see Table 2), the VxD will 
operate in Windows 3.0 as well, stealth.mak (Listing 4) is 
the makefile and stealth. Ink (Listing 5) is the link file for 
building the Stealth VxD using the DDK tools. By conven¬ 
tion, the resulting executable file should have a .386 ex¬ 
tension. 

The DDK provides four special tools for building VxDs: 
masm5, Iink386, addhdr, and mapsym32. 

masm5 is a special 32-bit, flat-model assembler that is 
intended for use with VxDS. Iink386 is a special 32-bit, 
flat-model segmented-executable linker for linking VxDS. It 
creates object files in the linear executable (LE) format that 
is necessary for VxDS, addhdr is a special utility used to 
add/modify header information of VxDS. This modification 
identifies the executable file as a VxD. mapsym32 is a 
special 32-bit version of the Mapsym utility; it converts 
map files produced by Iink386 into symbol files usable by 
debuggers. 

Talking to the Stealth VxD 

To install the VxD, simply add the following line to the 
[386Enh] section of the system, ini file: 

device={path)stealth.386 


Listing 4 stealth.mak 


# STEALTH - Windows Stealth 3.x VxD. 

# for DEBUG build, add -Zi for masm5, and /CO to link386. 
Debug=-DDEBUG 

all : stealth.386 

stealth.obj : stealth.asm stealth.inc stealth.def 
masm5 -1 -p -w2 -Mx $(Debug) stealth.asm; 

stealth.386: stealth.def stealth.obj 
link386 ©steal th. 1 nk 
addhdr stealth.386 
mapsym32 stealth 

copy stealth.386 c:\windows\system 


Listing 5 stealth.lnk 


stealth.obj 

stealth.386 /NOI /NOD /NOP 
stealth.map /MAP 

stealth.def 
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The code disk contains a simple Windows test program 
(testvxd.exe) that uses the Stealth VxD. It performs the 
| same operations a program would normally use to open a 
DOS device driver. It simply uses _lopen() to open a file 
named 'REGDEVNM' and uses INT 21h functions 4400h and 
4401h to set the device to raw mode. It then performs 
reads and writes to the file using JreadO and JwriteO. 

I purposely specified a large number (32Kb) in the sam¬ 
ple read request, in order to demonstrate that the request 
is not being broken up into 8Kb chunks. Remember, you 
can't be sure of this just by checking the returned read 
length in the TestVxD program, since DOSMGR will break 
up the read request, send each chunk to the device driver, 
and return a complete buffer back to the application, all 
transparently to the program. You can set a breakpoint in 
the VxD to determine how many times it is getting called 
and with what request sizes. For demonstration purposes, 
TestVxD calls the Stealth VxD's get version function and 
displays both the version number (returned in AX) and the 
last read length (returned in BX as a debugging variable). 

In order to check the version number of the VxD 
(which is also a good way to ensure the VxD was loaded), 
you must use the INT 2Fh protocol for communicating with 
VxDS. Windows provides several services and notifications 
via the multiplex interrupt (INT 2Fh) with functions in the 
1600h - 1686h range. The services allow DOS and Windows 
applications to retrieve the Windows version number, re¬ 
trieve the current VM ID, set critical sections, and get the 
addresses of entry points for VxD services. The notifica¬ 
tions are broadcast by Windows and generally involve 
Windows initialization and termination events. To receive 
notifications, install your own INT 2Fh handler and watch 
for the notification function in the AX register. 

Of particular interest to VxD developers is the Get De¬ 
vice Entry Point Address service (INT 2Fh, function 1684h), 
which expects a VxD ID in the BX register. Calling this serv¬ 
ice from a real-mode program retrieves the V86 entry 
point. Calling it from a protected-mode program retrieves 
the protected-mode entry point. A zero is returned if no 
VxD with that ID exists, or if the VxD doesn't export an 
API for the current processor mode. Otherwise, this func¬ 
tion returns with ES:DI pointing to the address of the API 
routine in the VxD. After you obtain the address of the 
VxD's API routine, you can simply load the function num¬ 
ber of the desired API in AX and call the API routine ad¬ 
dress. Figure 1 contains an excerpt from testvxd.c (avail¬ 
able on the code disk), showing how to call the get ver¬ 
sion API of the Stealth VxD. 

Debugging the Stealth VxD 

You can use Microsoft's 80386 Debugger, WDEB386, 
for debugging your VxD, but I chose to use Nu-Mega's 
Soft-lce/W debugger instead. Except for a problem with 
my video driver, Soft-lce/W performed very well, allowing 
me to set breakpoints and view data. The Trace_0ut and 
Debug_0ut macros are also helpful for tracking source code 
execution. 


If you intend to support both Windows 3.0 and Win¬ 
dows 3.1, you really must test your VxD thoroughly under 
both environments. For example, I discovered after much 
frustrating searching that during certain operations the 
carry flag was being set in Windows 3.0 and was not in 
Windows 3.1. 

Conclusion 

It would be a simple matter and quite beneficial to add 
open, close, read, and write functions to the API routines 
in the Stealth VxD. This would provide an even higher 
performance path for applications that wished to call the 
Stealth VxD directly, rather than go through the overhead 
of the INT 21h parsing. In fact, you might add disable and 
enable functions as well, so that applications could tempo¬ 
rarily disable most of this overhead if they were going to 
be calling the VxD directly. If disabled, the Stealth VxD 
would immediately pass on any INT 21h requests without 
parsing them. 

For completeness, consider adding a mechanism to se¬ 
rialize access to the read and write functions in your VxD. 
I had originally added code to fail on an open request if a 
handle to the device was already opened. I removed this 
code after discovering, regrettably, that several programs 
using my original DOS device driver did not handle access 
errors on file opens very nicely. 

The benefits to writing a VxD are quite significant (32- 
bit code that is running at ring 0, is accessing hardware 
directly, and is always active can yield much better per¬ 
formance) and the disadvantages (difficulty and poor 
documentation) are getting smaller. But even though VxDS 
provide crucial functionality on Windows 3.x and will re¬ 
portedly be supported by Windows 4.0, they are not sup¬ 
ported under Windows NT. 
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A VxD to Monitor DOS Output 

Paul Bonneau 


This article presents an enhanced-mode Windows DLL and VxD for monitor¬ 
ing the standard output (stdout) and standard error output (stderrj of DOS ses¬ 
sions running under Windows. The old-fashioned way of doing this is to redi¬ 
rect the DOS output to a file, and to read the file from a polling loop inside the 
monitoring Windows application. The old-fashioned approach is problematic 
(what if the file fills the disk?), error-prone, and slow. Using a VxD and DLL 
combination is a better solution, in that it exploits the 'natural' Windows/DOS 
interface functionality provided by VxDS. 

This article has its roots in a series of questions that have appeared in the 
Windows Q&A column recently about how to hook interrupts in Windows. Ton 
Plooy, a reader of the magazine who was also interested in the problem, wrote 
a VxD that not only hooked I NT 21h in the system virtual machine (VM), but 
also in other DOS VMs. At around the same time that Ton was implementing 
his VxD, another reader, David Dyck, sent in a question asking how to monitor 
DOS VM output in a Windows application. I have shamelessly used Ton's idea 
to answer that question, by intercepting INT 21h, function 40h (write file or de¬ 
vice), when the file handle is 7 (standard-out) or 2 (standard-error). Thanks to 
David for providing the theme for this article, and to Ton for (inadvertently) 
helping implement a solution. 

The High-Level View 

Figure 1 illustrates the operation of the VxD/DLL/Client task combination in 
response to a V86-mode int 21h of interest. At the heart of the VxD 
( wddjtee.386) is an int 21h ISR, Int21Hook(). The ISR is called whenever a V86- 
mode int 21h is raised, in the context of the interrupting VM. If the interrupt is 
in the context of a non-system VM, is for function 40h, and is directed to either 
stderr or stdout, the output buffer is copied into a per-VM circular queue. The 
VxD then schedules a callback to the internal function DoNotifyO, along with a 


Paul Bonneau was a developer of HyperChem, a molecular modeling system, and 
more recently, of Creative Writer, a word processor for children. He works for Microsoft 
Corporation as a Software Design Engineer. The opinions expressed in this article are 
Paul's alone and not those of Microsoft. 
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Figure 1 The VxD/DLUCHent task operation 
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Finally! C++ Custom Controls 

Ted Faison’s new winPAK™ custom controls are written entirely in C++ and OWL 2.0. 

Derive your own classes - Change any feature you want, disable features, 
or even add entirely new ones, using standard C++ inheritance. All member functions 
are virtual, so you can change any control feature. Here are some of the controls 
included in the package: 



|abd 

Validated input controls 

Hierarchical listboxes, as 
in BC4’s project manager 

V 

Analog gauges, in hundreds 
of different styles 

Horizontal and vertical faders 
to adjust analog variables 


Bitmapped listboxes, with 
horizontal scrollbars 

7oy. 

Progress Indicators 
in dozens of styles 

El 

Enhanced controls 

y 

Help tool, to build your own 
help systems without coding 


Spreadsheet controls, with 
full ODBC database access 

© 

Knobs, in dozens of styles 

IB 

ODBC compatible 

Form controls 

m 

Readouts, in text, LED, or 
odometer formats 


Data-aware Controls - most winPAK controls can be tied to database fields, 
to variables, or to other controls, using Resource Workshop. 

Customize your controls graphically - Forget archaic Visual Basic-style 
properties! winPAK controls have a built-in full-featured graphical designer, so you 
can design and customize controls interactively using the mouse. winPAK is fully 
compatible with Borland Resource Workshop. 

Reuse our winPAK Component Classes™ - All winPAK controls were 
implemented using our C++ Component Classes. These classes can be used to 
create entirely new object-oriented custom controls. 

Introductory Price $99.95 - Regular price $249.95. winPAK with source 
code $499.95. No royalties. Full 30 day money back guarantee. To order, call (714) 
854-6535 or (800) 500-6535. FAX (714) 854-6459. VISA, MasterCard accepted. 
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context switch to the system VM. When the virtual ma¬ 
chine manager (VMM) calls back to DoNotifyO, it will have 
switched contexts to the system VM, allowing DoNotifyO 
to call the notification procedure (UddjTeeNotifyProcO) in 
teedll.dll. UddjTeeNotifyProcO is really just a wrapper 
around the Windows API PostMessageO function, which is 
the only such function that Microsoft sanctions as safe to 
call at this point. PostMessageO passes the notification to 
the window that the client application registered, if there 
is one. When the client's window procedure later receives 
the notification, it is safe to call into the VxD to obtain the 
queued data. This is done through the DLL's exported 
function CchReadHvmO, which isolates the interface to the 
VxD from the client task. CchReadHvmO calls the VxD 
through the VxD's protected-mode API interface function. 

The VxD also monitors the creation and destruction of 
VMs. It does so by monitoring VM messages sent to its 
control procedure (a control procedure is part of every 
VxD, analogous to a window procedure). In particular, the 
message VM_Init signals the creation of a new VM, while 
VM_Terminate signals the destruction of an existent VM. 
Each time a new VM is created, wddjtee.386 uses the 
handy linked-list services provided by the VMM to create 
a new circular queue for use as the VM's data capture 
buffer. Likewise, when a VM is destroyed, wddjtee.386 re¬ 
moves and deallocates the VM's circular queue node. In 
addition to maintaining the linked list of circular queues, 
the VxD also notifies the DLL of VM creation and destruc¬ 
tion, using the callback mechanism described above. 
wddjtee.h (Listing 1) defines the three possible notification 
codes that can be passed to UddjTeeNotifyProcO: 
nfcVMCreate, nfcVMDestroy, and nfcDataReady. In addition to 
the notification code, the VxD also passes the correspond¬ 
ing VM handle. 

The VxD 

wddjtee.386 (see wddjtee.asm in Listing 2) is a fairly sim¬ 
ple VxD. Near the top, wddjtee.asm declares the data struc¬ 
ture CQS, which is used to maintain the per-VM circular 
queue. I chose a queue since the communication between 
the VxD and the client task is asynchronous. Incoming 
data is written at the tail of the queue, and the client task 
obtains data from the head. If overflow occurs, data at the 
head of the queue is lost. I chose a circular queue buffer 
of 64Kb; this allows the queue to hold, without overflow¬ 
ing, the maximum data size that a DOS program can write 
in on INT 21h call (64k - 1 bytes) without overflow. The 
buffer is implicitly located at the end of the COS. The first 
two members of the CQS, hvm and vmi, hold the VM handle 
and ID of the associated VM. Next come the buffer posi¬ 
tions of the head and tail of the queue, ibHead and ibTail. 
Lastly, the flags fOverflow and flnNotify are used to signify 
that an overflow condition has been detected, and that a 
data available notification is pending. 

wddjtee.asm has two global variables. The first, 
hlstQueue, is the handle for the linked list of CQS data struc¬ 
tures. The second, lpfnNotify, contains the address of the 
16-bit, protected-mode function (in the system VM) to call 
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GSS*CGI Graphic Tools now from EMATEK 

Soon available on all platforms: 

MS-Windows, Windows NT, OS/2 PM, Solaris, UNIX on PCs and workstations. 
Your application written with the GSS*CGI Graphic Tools 
will be portable to all platforms. 


GSS*GDT 



Graphics Development Toolkit enables you to develop 
applications in a device and system independent way 
through the help of device-specific drivers based on the 
ISO CGI Standard. GSS'GDT consists of a library with 
more than 160 callable C and FORTRAN functions and is 
compatible with the graphics development tools from IBM 
and SCO. 

GSS*GDT is available for DOS, MS-Windows, Windows 
NT, OS/2 PM, Interactive Unix, Onsite Unix SVR 4.2 and 
Solaris. 

Versions for SCO Unix, UnixWare and HP Workstations will 
be soon available. 


GSS*GKS 


iraphical Kernel System is a C and FORTRAN function 
library that enables you to develop portable graphic 
applications which include e.g. user interaction, coordinate 
transformation and object segmentation, based on the ISO 
GKS Standard. GSS*GKS, which is installed in large 
quantities on the DOS platform and has been proved 
successful for years, is now available for the graphical user 
interfaces and therefore offers the software developer a 
smooth transition to the new windowing systems. 
GSS*GKS is available for DOS, MS-Windows, Windows 
NT, OS/2 PM, Interactive Unix, Onsite Unix SVR 4.2 and 
Solaris. 

Versions for SCO Unix, UnixWare and HP Workstations 
will be soon available. 


GSS*EVT 





=* 

GSS*GCT 

-4 


EMATEK Vectorfont Toolkit enables you to integrate 
vectorfonts into your application. Supported font formats 
are PCL5, PostScript Type 1, TrueType and Bitstream 
Speedo. GSS*EVT offers a variety of additional elements 
and attribute functions like character height and gap, 
rotation and italicize angle, fill area pattern and outline- 
width, shadow, background boxes, leader and underlining 
as well as sub- and superscripting for scientific purposes. 
GSS'EVT is an add-on for GSS'GDT, GSS*GKS, 
MS-Windows SDK and will be ported to all popular 
graphical user interfaces. 


Graphics Charts Toolkit provides you with high-level 
functions to integrate presentation graphics into your 
application. With only a few calls you can output pie, bar, 
line, step, schedule or text diagrams on a display or 
printer. Each part of the chart can be altered through the 
related attribute functions. GSS*GCT is an add-on for 
GSS*GDT and GSS*GKS and will be ported to all popular 
graphical user interfaces, thus providing portable presen¬ 
tation graphic capabilities for all supported systems. 
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Listing 1 wddjtee.h — Interface to WddjTee VxD 
and DLL 



I* wddjtee.h *1 

/* -- Interface to WddjTee VxD and DLL. */ 



typedef DWORD (CALLBACK * LPFN_VXD)(void); 


/* Protect-mode API function numbers. */ 

♦define apiGetVersion 0 /* Get VxD version #. */ 
♦define apiRead 1 /* Read output buffer. */ 

♦define apiRegister 2 /* Register a callback. */ 

/* VxD notifcation codes. */ 

♦define nfcVMCreate 0 /* Hew VM created. */ 

♦define nfcVMDestroy 1 /* VM destroyed. */ 

♦define nfcDataReady 2 /* Data for VM is available. */ 

/* Miscellaneous constants. */ 

♦define wWddjTeeDeviceld 0x31b3 /* VxD ID from MS. */ 
♦define wWddjTeeVersion 0x0101 /* VxD version. */ 

/*****************************************************/ 
/* DLL Interface. */ 

/*****************************************************/ 
/* Prototypes. */ 

BOOL CALLBACK _export FRegisterWnd(HWND hwnd); 

BOOL CALLBACK _export FUnregisterWnd(HWND hwnd); 

UIHT CALLBACK _export CchReadHvm(DWORD hvm. 

LPSTR lprgch, BOOL far *lpfOverflow); 

/* DLL notifcation messages. */ 

♦define wmVMCreate (nfcVMCreate + WMJSER) 

♦define wmVMDestroy (nfcVMDestroy + WMJSER) 

♦define wmDataReady (nfcDataReady + WMJSER) 

/* Maximum read buffer size. */ 

♦define cbReadMax (0x10000 - 0x18 - 1) 

/* End of File */ 


Developer's Toolkit 
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with notification codes. The DLL supplies this address to 
wddjtee.386 during initialization. 

Next comes the VxD's virtual device declaration. Just as 
every Windows program possesses a UinMainO function, 
every VxD possesses a virtual device declaration. This dec¬ 
laration names the VxD and specifies its major and minor 
version numbers, the address of the control procedure, the 
VxD's device ID, where it loads with respect to other VxDS 


Listing 2 wddjtee.asm — VxD traps writes to 
stdout and stderr and “tees” them through a PM callback 


. ***************************************************** 
; WddjTee.asm 

; -- VxD traps writes to stdout and stderr and "tees" 

: them through a PM callback. 

. 386p 



include vmm.inc 


Constants. 

***************************************************** 


wDeviceld equ 31b3h 
bVersionMajor equ 01 
bVersionMinor equ 01 


Device id from Microsoft. 
Major byte of version number. 
Minor byte of version number. 


wVersion equ (bVersionMajor * 256 + bVersionMinor) 
cbQueue equ 10000h ; Size of a circular queue. 
nfcVMCreate equ 0 ; New VM created. 

nfcVMDestroy equ 1 ; VM destroyed. 

nfcDataReady equ 2 ; Data for VM is available. 



CQS struc ; Circular Queue Structure, 
hvm dd (?) ; VM handle, 

vmi dd (?) ; VM ID. 

ibHead dd (?) ; Read end. 

ibTail dd (?) ; Write end. 

fOverflow dd (?) ; If overflow occured. 
flnNotify dd (?) ; Client notified of data ready. 
; Array of cbQueue bytes here. 

CQS ends 



VxDJATAJEG 

histQueue dd (0) ; Handle to list of circular queues. 
lpfnNotify dd (0) ; Client callback. 


; Protect mode API dispatch table, 
rgpfn label DWORD 

dd offset32 WGetVersion 
dd offset32 CchRead 
dd offset32 RegisterLpfn 
cpfn = ($ - rgpfn) / 4 - 1 
VxDJATA.ENDS 

.***************************************************** 
; Device header. 

.***************************************************** 
Declare_VirtualJevice wddjtee, bVersionMajor, \ 
bVersionMinor, DispatchControl, wDeviceld. \ 
Undefinedjnitjrder,, PMApi 

VxD_Locked_Code_Seg 

; Control procedures. 


BeginProc DispatchControl 

; -- Control dispatcher. 

Begin_Control Jispatch 

Control Jispatch Devicejnit, VxDInit 

Control Jispatch VMJnit, VMInlt 

ControlJispatch VM_Terminate, VMEnd 

Endjontrol Jispatch 

clc 

ret 

EndProc DispatchControl 
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(the initialization order), its V86 mode API (wddjtee.386 has 
none), and its protected-mode API. 

The next section contains the control procedure and its 
helper functions. In every VxD example I have found, the 
control procedures is located in a locked code area delim¬ 
ited by the VxD_Locked_Code_Seg and VxD_Locked_Code_Ends 
macros. This implies that a VxD's control procedure code 
cannot be paged, but in reality, no VxD code is ever 


paged in Windows 3.1 (don't confuse this with the fact 
that a VxD's real-mode initialization code is discarded). In¬ 
deed, the 'normal' code declaration macros, VxD_Code_Seg 
and VxD_Code_Ends, equate to the locked variants (see the 
file 386\include\vmm.inc in the DDK). My guess is that a fu¬ 
ture version of Windows will page code segments not ex¬ 
plicitly declared as locked. 


Listing 2 continued 


BeginProc VxDInit 

.***************************************************** 
; -- Install the V86 Int 21h hook and create the list 
; of per-VH circular queues. 
.***************************************************** 

push esi 

mov eax, LF_Use_Heap OR LF_Alloc_Error 

mov ecx, cbQueue + size CQS 

VMMCall List.Create ; Create list. 

mov [histQueue]. esi 

jc short VxDInitFail ; Quit if failed. 

mov eax, 21h ; Set ISR. 

mov esi. 0FFSET32 Int21Hook 

VMMCall Hook_V86_Int_Chain 

jc short VxDInitFail ; Quit if failed. 

clc 

VxDInitFail: 
pop esi 

ret 

EndProc VxDInit 


VMMCall 

Test Sys VM Handle 

DOS box? 

jz short 

VMInitDone 

No. so skip. 

mov 

esi. [histQueue] 

Allocate a new node. 

VMMCall 

List_Allocate 


jc short 

VMInitDone 

Did’na work capt'n! 

VMMCall 

List Attach 

Link it in. 

mov 

[eax].ibTai1, 0 

Initialize members. 

mov 

[eaxj.ibHead, 0 


mov 

[eax].hvm. ebx 


mov 

ebx, [ebx].CB_VMID 

Control block has ID 

mov 

[eax].vmi, ebx 


mov 

[eax].fOverflow. 0 


mov 

[eaxj.flnNotify, 0 


mov 

ebx, eax 


mov 

eax, nfcVMCreate 


call 

NotifyClient 



VMInitDone: 

clc 

ret 

EndProc VMInit 


BeginProc VMInit 

. ***************************************************** 

; -- Allocate a circular queue for this VM. 
.***************************************************** 


BeginProc VMEnd 

.*****************************************************. 
; -- Free the circular queue for this VM. ; 
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In any case, the first routine in the 'locked' code seg¬ 
ment is DispatchControK), named as the VxD's control pro¬ 
cedure in the Declare_Virtual_Device macro. This routine 
will be called by the VMM when various events occur, but 
my implementation deals only with the messages De- 
vice_Init, VM_Init, and VM_Terminate. I use the DDK conven¬ 
ience macros Begin_Control_Dispatch, ControlJispatch, and 
End_Control_Dispatch to build a boilerplate dispatch proce¬ 


dure without having to write a single line of assembly 
code. For each message to be handled, all I need to do is 
supply the Control_Dispatch macro with the message con¬ 
stant and the address of a handler routine. 

VxDInitO is the handler routine for the Device_Init mes¬ 
sage. This is one of three messages the VMM sends to a 
virtual device during initialization. The first message sent 
is Sys_Critical_Init. This message is sent with interrupts 


Listing 2 continued 



pushad 

call 

PcqsFindHvm 

PcqsFindHvmNotFound: 


jc short 

VMEndDone 

stc 


mov 

eax, nfcVMDestroy 

ret 


call 

NotifyClient 

PcqsFindHvmFound: 


VMEndDone: 


mov ebx, eax 


popad 


clc 


clc 


ret 


ret 


EndProc PcqsFindHvm 


EndProc VMEnd 

VxD_Locked_Code_Ends 



BeginProc PcqsFindHvm 

.***************************************************** 
; -- Find the circular queue for the given VM. 

; EBX : VM handle on input, node on output. 

; -- If found carry is clear, else carry is set. 

. ***************************************************** 

mov esi, [hlstQueue] 

VMMCall List_Get_F1rst ; Get first node. 

PcqsFindHvmGetNext: 

jz short PcqsFindHvmNotFound ; Failure if at end. 
cmp [eax].hvm, ebx ; Is this it? 

jz short PcqsFindHvmFound ; Yupper. 

VMMCall List_Get_Next ; Get next node, 

jmp short PcqsFindHvmGetNext 
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VxD_Code_Seg 

.***************************************************** 
; Procedures. 

.***************************************************** 


BeginProc Int21Hook 


-- Virtual 86 mode int 21h hook function. 
***************************************************** 


pushad 


Save regs. 

mov 

ax, [ebp].Client AX 

Function number. 

cmp 

ah. 40h 

Write? 

Jne 

Int21HookNextHandl er 

No, so skip. 

VMMCall 

Test Sys VM Handle 

DOS box? 

jz 

Int21HookNextHandler 

No. so skip. 

cmp 

[ebp].Client_BX, 1 

< stdout? 

ji 

Int21HookNextHandler 

Yes, so skip. 

cmp 

[ebp].Client BX. 2 

> stderr? 

jg 

Int21HookNextHandler 

Yes, so skip. 

cmp 

[ebp].Client CX, 0 


jz 

Int21HookNextHandler 


: Find queue node. 


call 

PcqsFindHvm 


jc short 

Int21HookNextHandler 


mov 

edi, ebx 


add 

edi, size CQS 

pcqs->rgb. 

add 

edi, [ebx].ibTail 


; Get linear address of buffer. 


movzx 

esi, [ebp],Client DS 

Src segment. 

shl 

esi, 4 

Linearize 

movzx 

eax, [ebp].Client DX 

plus offset. 

add 

esi, eax 


; Get length of copy. 


movzx 

ecx, [ebp].Client CX 

# bytes out. 

call 

CbCqs 

# bytes queued. 

neg 

eax 


add 

eax, cbQueue - 1 

# bytes free. 

cmp 

ecx, eax 

> queue size? 

jl short 

Int21HookGot0verfiow 


mov 

[ebx].fOverflow, 1 

Remember fact. 

Int21HookGot0verflow: 


mov 

eax, [ebx].ibTail 

Current write pos. 

add 

eax, ecx 

Calculate new 

call 

WMod 

write position and 

mov 

[ebx].ibTail, eax 

record it. 

Int21HookGotRead: 


cmp 

[ebx].fOverflow, 0 

Overflow? 

jz short 

Int21HookSetupLoop 

No, we’re ok. 

inc 

eax 

Yes, so position 

call 

WMod 

read 1 past write 

mov 

[ebx].ibHead, eax 

pos. 

Int21HookSetupLoop: 


cld 


Prepare for loop. 

mov 

eax, ebx 


add 

eax, cbQueue + size CQS 

Int21HookCopyLoop: 


cmp 

edi. eax ; 

Wrapped? 

jl short 

Int21HookNoWrap ; 

No, we’re ok. 
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disabled and is only for time-critical initialization code. The 
last message, Init_Complete, is sent just before the VMM 
frees the VxD's real-mode initialization code. The DDK rec¬ 
ommends that most VxDS do the bulk of their initializa¬ 
tion upon receipt of the middle message, VMJnit. This is 
where, among other things, a VxD specifies instance data 
(unique data mapped to the same linear address in each 
VM), and allocates and initializes VxD-specific control 


Listing 2 continued 


mov edi, ebx ; Yes, restart, 

add edi. size CQS 


Int21HookNoWrap: 

movsb 

loop Int21HookCopyloop 


; Copy a byte. 

; Until no more. 


block data (the VM handle is actually a pointer to a data 
structure called the VM control block - see Kelly Zytaruk's 
article in Andrew Schulman's 'Undocumented Corner" in 
the Jan. '94 issue of Dr. Dobb's Journal for a description of 
this structure). 

VxDInitO allocates a linked list by calling the VMM 
function List_Create, specifying the size of a circular queue 
node. VxDInitO next installs the V86-mode INT 21h ISR, 


mov ax. [ebp].Client_E$ ; Selector, 

shl eax, 16 

mov ax, [ebp].Cl1ent_DI ; Offset. 

mov [lpfnNotify], eax 

ret 

EndProc Registerlpfn 


; Notify client of new data. 

cmp [ebx].fInNotlfy. 0 ; Is one pending? 

jnz short Int21HookNextHandler 

mov [ebx].fInNotlfy, 1 

mov eax, nfcDataReady 

call NotifyCllent 

Int21HookNextHandler: 

popad ; Restore regs. 

stc ; Chain to next, 

ret 

EndProc Int21Hook 
BeginProc CbCqs 

. ***************************************************** 
; -- Return the number of bytes in the queue. 

; On input : EBX : pointer to CQS. 

; On output : EAX : number of bytes. 

mov eax, [ebx].IbTail 

sub eax, [ebx].IbHead 

add eax, cbQueue 

call WMod 

ret 

EndProc CbCqs 
BeginProc WMod 

.*-******************************************♦********* 
: -- Return the mod of the input argument (eax) with 
; the queue size (cbQueue) in eax. 


push 

edx ; 

Save these guys. 

push 

ecx 


xor 

edx, edx ; 

Clear hi 32 bits. 

mov 

ecx. cbQueue ; 

Can’t use immediate 

idi v 

ecx ; 

operand in division. 

mov 

eax, edx ; 

Get remainder. 

pop 

ecx ; 

Restore these guys. 

pop 

edx 


ret 



EndProc WMod 


BeginProc PMApi, Public 


: -- Main dispatch point for protected mode API. 

; -- On input 



: -- C11ent_AX : API id to execute. 

; *- Jump to corresponding API routine. 

movzx 

eax, [ebp].Client_AX ; Function number. 

cmp 

ax, cpfn 

; Mithln range? 

ja short 

PMApiDone 

i No, so exit. 

jmp 

rgpfn[eax * 4] 

i Yes, call handler 


PMApiDone: 

ret 


EndProc PMApi 


; -- Return the version number. 

. **««*********************************************** 

BeginProc WGetVersion, Public 

mov [ebp].Cl1ent_AX, wVersion 
ret 

EndProc WGetVersion 

BeginProc RegisterLpfn, Public 
.*******★*********************★*********************** 

; -- Register the client’s callback function. 

; -- Cl 1ent_ES:Cl 1ent_DI : Pointer to callback. 

.**intiHYihttHt******** ********************** ************* 


BeginProc CchRead, Public 

. ***************************************************** 
; -- Read the bytes tee’d from the given VM. 

; On Entry: 

; -- Cl 1ent_DX:Client_BX : VM handle. 

; On Exit: 

; -- Client_DS:Client_SI : Output buffer. 

; -- C11ent_ES:C11ent_DI : Overflow flag pointer. 

; -- C11ent_AX : # bytes copied. 

push es ; Save stuff 

pushad 

mov [ebp].Cl1ent_AX, 0 ; Assume failure. 

mov bx. [ebp].Cl1ent_DX ; Get VM handle. 

shl ebx, 16 

mov bx. [ebp].Client_BX 

VMMCall Validate_VM_Handle ; Is it valid? 

jc CchReadDone ; No, so exit. 
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Int21Hook(), with the VMM's Hook_V86_Int_Cha1n routine. If 
all went well, VxDInitO returns with the carry flag clear to 
indicate success. Otherwise, it leaves the carry set (as it 
must have been following a failed call to either List_Cre- 
ate or Hook_V86_Int_Chain) which causes the VMM to abort 
the loading of wddjtee.386. 

When DispatchControlO receives a VM_Init message, it 
calls VMInitO to handle it. VMInitO's job is to allocate and 


link a CQS node for the VM, and to initialize the fields of 
the CQS. In a bit of paranoia on my part, VMInitO first tests 
to see if the current VM is the system VM; if so, it skips its 
normal processing. I don't think a VxD can receive a 
VMJnit message for the system VM in version 3.1 of Win¬ 
dows, but l don't know about the future. Also, I should 
mention that I have not tested this VxD with Windows for 
Workgroups 3.1, which uses a hidden VM (hidden VMs 


Listing 2 continued 


call 

PcqsFindHvm 

Find queue node. 

add eax. cbQueue + size 

CQS ; address. 

jc short 

CchReadDone 

Not found. 

cld 

: Prepare to loop. 

mov 

es. [ebp].C11ent_ES 

Get flag address. 

CchReadDoLoop: 


movzx 

ecx, [ebp].Cl1ent_DI 


cmp esi, eax 

; Wrapped? 

mov 

eax, [ebx].fOverflow 


jl short CchReadNoWrap 

i No. we’re ok. 

mov 

es:[ecx], ax 

Set contents. 

mov esi. ebx 

; Yes. start over. 

mov 

[ebx].fOverflow, 0 


add esi, size CQS 





CchReadNoWrap: 


call 

CbCqs 

# bytes to copy. 

movsb 

; Copy a byte. 

mov 

[ebp].C11ent_AX, ax 

Return t bytes. 

loop CchReadDoLoop 

: Until no more. 

or 

eax, eax 

Are there any? 



jz short 

CchReadDone 

No, so exit. 

CchReadDone: 


mov 

ecx, eax 

Loop counter. 

popad 

: Restore stuff. 




pop es 


mov 

es, [ebp].Client DS 

Get dest buffer. 

ret 


movzx 

edi, [ebp].Client SI 


EndProc CchRead 


mov 

esi, ebx 

Get head address. 



add 

esl, size CQS 

pcqs->rgb 

BeginProc NotifyClient, Public 


mov 

eax, [ebx].ibHead 





add 

esi, eax 

+ pcqs->ibHead. 


-- Schedule call back to system VM to call client’s 





notification callback. 


add 

eax, ecx 

Get new head. 


-- EAX : Notifcation code. 


call 

WMod 



•• EBX : Queue node. 


mov 

[ebx]-ibHead. eax 

Record it. 







pushad 


mov 

eax, ebx 

Get source limit 

cmp [lpfnNotlfy], 0 



jz short NotifyClientDone 
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mov 

edx, [ebx].vmi ; 

AX <-* 

code, hi 16 bits 

shl 

edx, 16 ; 

gets VM 

1 id. 

or 

edx, eax 



VMMCall 

Get_Sys_VM_Handl ( 

; : Call 

sys VM. 

mov 

esi, offset32 DoNotify 


VMMCall 

Call_VM_Event 




NotifyClientDone: 

popad 

ret 

EndProc NotifyClient 
BeginProc DoNotify, Public 
; -- Post notifcation to client via callback, 
pushad 

Push_Client_State 

VMMCall Begin_Nest_Exec 

mov eax. edx ; Notification code. 

VMMCall Simulate_Push 

mov ebx, edx ; Get VM id. 

shr ebx, 16 

call PcqsFindVml ; Get queue, 

cmp dx, nfcDataReady 

jnz short DoNotifyPushVmh 

mov [ebxj.flnNotlfy, 0 

DoNotlfyPushVmh: 

mov eax, [ebx].hvm ; VM handle, 

shr eax, 16 

VMMCall Simulate_Push ; Hi 16 bits, 

mov eax, [ebx].hvm ; VM handle. 

VMMCall Simulate_Push ; Lo 16 bits. 

cmp dx, nfcVMDestroy 

jnz short DoNotifyCall 

mov eax, ebx 

VMMCall List_Remove 

mov eax, ebx 

VMMCall List.Deallocate 

DoNotifyCall: 

mov cx, word ptr [lpfnNotlfy + 2] 

movzx edx. word ptr [lpfnNotlfy] 

VMMCall Simulate_Far_Call 

VMMCall Resume_Exec 

VMMCall End_Nest_Exec 
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are not documented by Microsoft). I see no reason why it 
shouldn't work, but you might want to test it first. 

After calling the VMM services L1st_Allocate, to allocate 
a CQS node, and List_Attach, to insert it into the linked list 


Listing 2 continued 

Pop_C11ent_State 

popad 

ret 

EndProc DoNotify 


BeginProc PcqsFindVml 


; -- Find the circular queue for the given VM ID. ; 

; EBX : VM ID on Input, node on output. ; 

; If found carry is clear, else carry is set. ; 

mov esi, [hlstQueue] 

VMMCall L1st_Get_F1rst 

Get first node. 

PcqsFindVmlGetNext: 

jz short PcqsFindVmlNotFound 
cmp [eax].vmi, ebx 

jz short PcqsFIndVmiFound 
VMMCall L1st_Get_Next 
jmp short PcqsFindVmiGetNext 

Failed if at end. 

Is this it? 

Yupper. 

Get next node. 

PcqsFindVmiNotFound: 
stc 
ret 


PcqsFindVmiFound: 
mov ebx, eax 

clc 
ret 

EndProc PcqsFindVml 

VxD_Code_Ends 

End 

; End of File 
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of CQS s, VMInitO initializes the fields of the CQS and calls 
the utility function NotifyClientO to inform the DLL that a 
new VM has been created (more on NotifyClientO later). 

The last control procedure, VMEndO, is called when Dis- 
patchControlO receives a VM_Terminate message. You may 
suppose that this routine will remove the CQS node for the 
current VM, free the node, and notify teedll.dll. Not sol 
The routine does have to notify teedll.dll, but it must not 
free the node. The problem is that notification is asyn¬ 
chronous, and so will not yet have occurred by the time 
VMEndO returns. However, notification involves extracting 
data from the CQS, so the CQS cannot be deallocated until 


Listing 3 wddjtee.def — Linear linker definition file 
for WddjTee VxD 


wddjtee.def 

-- Linear linker definition file for WddjTee VxD. 


LIBRARY WddjTee 

DESCRIPTION ’DOS app name utility* 

EXETYPE DEV386 

SEGMENTS 

_LTEXT PRELOAD NONDISCARDABLE 
_LDATA PRELOAD NONDISCARDABLE 
.TEXT CLASS ’PCODE’ NONDISCARDABLE 
_DATA CLASS ’PCODE’ NONDISCARDABLE 

EXPORTS 

wddjtee.DDB 


Listing 4 makefile — Project file for WddjTee VxD 


M makefile 

IHI 

IHI -- Project file for WddjTee VxD. 

H 


all: wddjtee.386 teedll.dll teelist.exe 


wddjtee.386: wddjtee.obj wddjtee.def 

link386 wddjtee.obj.wddjtee.386 /NOI /NOD /NOP \ 
/MAP..,wddjtee.def 
addhdr wddjtee.386 
mapsym32 wddjtee 
copy wddjtee.386 \win\systen 

wddjtee.obj: wddjtee.asm 

masm5 -p -w2 -Mx -Zd wddjtee: 


Listing 5 teedll.c — DLL receives notifications 
from wddjtee.386 and informs client task 


/♦teedll.c */ 
/* -- DLL receives notifications from wddjtee.386 */ 
/* and informs client tasks. */ 
/* - To build: cc -2 -wd -d -DSTRICT teedll.c */ 


/*****************************************************/ 
♦include <windows.h> 

♦include "wddjtee.h" 


LPFNJXD lpfnVxD; /* VxD entry point. */ 
HWND hwndClient; /* Client window. */ 


void CALLBACK _export 
WddjTeeNotifyProc(WORD nfc, DWORD hvm); 
int CALLBACK _export WEPOnt wExit); 

int CALLBACK LibMainCHINSTANCE hins. WORD ds. 

WORD cbHeap. LPSTR lsz) 

/I.****************************************************/ 

/* ■■ Register with wddjtee.386. */ 
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after the notification has taken place. I have relocated this 
bit of housekeeping code inside the notification code. 

When VMEndO is called, EBX will contain the current VM 
handle, but VMEndO needs to obtain the address of the cor¬ 
responding CQS node, since NotifyClientO requires a CQS 
address as one of its parameters. VMEndO obtains the CQS 
node with the helper function PcqsFindHvmO. PcqsFindHvmO 
walks the linked list of CQS s, looking for one whose VM 
handle (hvm field) matches the current VM handle in EBX. If 
it finds one, it returns the address of the node and clears 
the carry flag. Otherwise it returns with the carry flag set. 

The next routine in wddjtee.asm is the ISR, Int21Hook(). 
This routine will get called every time any VM issues an 
INT 21h, so it can affect performance. 

Even if this routine is as fast as possi¬ 
ble, the overhead of calling it in the 
V86 INT 21h chain may be enough to 
noticeably degrade performance. 

However, there is no reason to leave 
the ISR in place if no client task is 
using the VxD. You could modify the 
code to set and remove the hook dy¬ 
namically in response to the exist¬ 
ence of a client task. With this ap¬ 
proach you would only see the deg¬ 
radation when actively monitoring a 
VM. You can even go a bit further, 
and remove the ISR even if there is 
an active client task as long as the 
system VM is the only VM. For the 
sake of simplicity I have imple¬ 
mented neither of these optimiza¬ 
tions. 

Int21Hook() begins with a series of 
tests that must be passed to process 
the interrupt. The function number 
must be 40h, the VM must not be the 
system VM, the output handle must 
be either 7 (stdout) or 2 (stderr 1 ), and 
the buffer size must be greater than 
zero. If any of these tests is not met, 
the code jumps to the exit point, 
which sets the carry flag and returns 
so that the VMM can call the next 
handler. 

If all the conditions are met, 

Int21Hook() calls PcqsFindHvmO to ob¬ 
tain the CQS node for the current VM. 

If for some reason no node can be 
found (the allocation could have 
failed when the VM initialized), the 
code jumps to the exit point. Since 
Int21Hook() is going to use the MOVSB 
string instruction to copy the output, 
it sets the address of the tail of the 
queue into the destination register, 

EDI. The next four instructions linear¬ 
ize the real-mode paragraph :offset 
address in the Client Register Struc¬ 
ture's DS:DX register pair (the source 


Listing 5 continued 



( 

800L fVal = FALSE; 


/* Get VxD entry point. */ 

_asm push es; 

_asn push di; 

_asm xor di. di; 

_asB mov es. di; 

_asm mov ax. 0x1684; 

_asm mov bx, wWddjTeeDevIceld; 

_asm int 0x2f; 

_asm mov word ptr [lpfnVxD], di; 
_asm mov word ptr [lpfnVxD + 2], es; 
If (NULL == lpfnVxD) 
goto LExit; 


Rev Up Database 
Programming 

with Greenleaf Database Library 



Powerful Functions 


□ The SoftC Database Library 
is now the new Greenleaf 
Database Library. 

□ Unsurpassed speed and 
flexibility for access to 
industry standard database 
data, index, and memo files 
at an affordable price. 

□ Databased Advisor says, 
"SoftC Database Library has 
top ratings!" 

□ Don't be fooled by pretty 
ads—the Database Library is 
all you need to interface 
with dBASE III, dBASE IV, 
FoxPro, FoxBASE, Clipper, 
dBXL, and other xBASE files 
including new FoxPro CDX 
index files. 

□ Supports MS-DOS, 
Windows™, and is portable 
to OS/2, UNIX. 

□ Includes Windows 3.1 DLL, 
supports Microsoft, Borland 
and Zortech C/C++. 

□ Single and Multiple User; 
Network acccess fully 
supported. 

□ Database package not 
required—this product is a 
complete ISAM library. 

□ Windows DLL linkable with 


most DLL-capable compilers 
(including Visual Basic). 


All Greenleaf Libraries Feature: 

□ No royalties 

□ 90-day money-back guarantee 
FREE unshrouded source (ANSI & K&R) 
FREE unlimited tech support 
Top rated documentation AND online 
documentation with FREE help engine! 

FREE BBS access, quarterly newsletter 
GOLD support available: toll-free access to 
BBS, tech support and free updates—call for 
prices 

Database Library v3.22 .. $249 

Call today for complete infor¬ 
mation, demo, or to order. Mas¬ 
terCard, VISA, AmEx, approved 
purchase orders. 

1 - 800 - 523-9830 

214-248-2561 
FAX 214-248-7830 
BBS 214-250-3778 
Greenleaf Software, Inc. 
16479 Dallas Parkway, Suite 570 
Dallas, TX 75248 

m 

GREENLEAF 
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buffer being output), and store the result in the copy 
source register, ESI. The Client Register Structure (CRS) is a 
snapshot of the VM's CPU registers when the VxD was 
called. It is used for both input to and output from the 
VxD. the CPU registers will be restored from the CRS when 
the VM regains control. The CRS is defined in vim. Inc. 

Since linear addresses are being used for both source 
and destination, the segment registers DS and ES do not 
have to be modified, as they both hold the linear data 
selector. 


Int21Hook() then obtains the length of the output string 
and compares it with the amount of space remaining in 
the circular queue. It does this by calling CbCqsO, a utility 
function that returns the amount of data already in the 
queue, negating the answer, and adding back in the total 
queue capacity (the total queue capacity is one less than 
the size of the queue buffer since when the head and tail 
are the same the queue is empty; thus if the tail is just 
behind the head there are n - 1 elements in the queue 
where n is the size of the buffer). If the output string is 


Listing 5 continued 


/* Make sure expected version is installed. */ 
_asm mov ax, apiGetVersion; 
if ((W0RD)(*1pfnVxD)() < wWddjTeeVersion) 
goto LExit; 

/* Register notification callback. */ 

_asm push cs; 

_asm pop es; 

_asm mov dl. offset WddjTeeNotifyProc; 

_asm mov ax, apiRegister; 

(*lpfnVxD)(); 
fVal = TRUE; 

LExit: 

_asm pop di; 

_asm pop es; 

return fVal; 

} 


int CALLBACK _export WEP(int wExit) 
/* -- Remove notification callback. 

{ 


Windows Tools 


Ad Oculos 

The low cost SDK 
for industrial 
image analysis 

Multiple fonts and / More than 50 powerful 
paragraph formatting / algorithms with source code 
Optional image import / Easy integration of user-defined 
with 1C Image-Control / algorithms 

Visual Basic interface / More than 20 sample applications 

Macrofields / Needs no additional hardware 

RTF filter,... / Award for best scientific software 1992 

Get your free TX demo today! Text book on the basics of 
image processing with Ad Oculos demo: $49 

Call 913 832 2070 (North and South America) 

ESC, Fax 913 832 8787, CompuServe 71 141,3624 

Elsewhere contact: DBS GmbH, Germany, 

+49 421 2208 161, Fax: +49 421 2208 273 
CompuServe 100013,115 

Or download TXDEMO.ZIP and AODEMO.ZIP from 
CompuServe, Forum WINSDK, Section Public Utilities 
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_asm push es; 

_asm xor ax, ax; 

_asm mov es, ax; 

_asm mov dl, ax; 

_asm mov ax, apiRegister; 

(*lpfnVxD)(); 

return TRUE; 

} 


BOOL CALLBACK _export FRegisterWnd(HWND hwnd) 

/* -- Register a window to notify. */ 

/*****************************************************/ 

{ 

if (NULL == hwndClient) 

{ 

hwndClient = hwnd; 
return TRUE; 

} 

return FALSE; /* Someone beat you to it! */ 

} 


BOOL CALLBACK _export FUnregisterWnd(HWND hwnd) 
/* -- Remove a window to notify. 


{ 

if (hwndClient == hwnd) 

{ 

hwndClient = NULL; 
return TRUE; 

} 

return FALSE; 

} 


void CALLBACK _export 
WddjTeeNotifyProc(WORD nfc, DWORD hvm) 

/*****************************************************/ 
/* -- Notify all registered windows. */ 

/***************************************************** j 
{ 

if (NULL != hwndClient) 

PostMessage(hwndClient, nfc + WMJSER. 0, hvm); 

} 


UINT CALLBACK _export CchReadHvm(DWORD hvm. 
LPSTR lprgch, BOOL far *lpfOverflow) 


Read the output for the given VM. 


{ 

LPFNJXD lpfnVxDT = lpfnVxD; 
UINT cb; 


_asm push ds; 

_asm push es; 

_asm pusha; 

_asm mov dx, word ptr 
_asm mov bx, word ptr 
_asm mov ds, word ptr 
_asm mov si, word ptr 
_asm mov di, word ptr 
_asm mov es, word ptr 
_asm mov ax, apiRead; 
(*1pfnVxDT)(); 

_asm mov cb. ax; 

_asm popa; 

_asm pop es; 

_asm pop ds; 
return cb; 

} 

/* End of File */ 


[hvm + 2]; 

[hvm]; 

[lprgch + 2]; 
[lprgch]; 

[1pfOverflow]; 
[lpfOverflow + 2]; 
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bigger than the available queue space, the overflow flag is 
set. 

The utility function CbCqsO calculates the amount of 
data in the queue by implementing the expression: 

(tail - head + cbQueue) % cbQueue, 

where cbQueue is the size of the circular queue buffer. 
CbCqsO in turn uses the utility function UModO, which com¬ 
putes the modulus of its input argument (in EAX) with the 
queue size (cbQueue). 

So, having checked for overflow, Int21Hook() is now 
ready to determine the new tail position, and if overflow 
has been detected, to reposition the new head one past 
the new tail. The new tail is calculated using: 

tail = (tail + byte_count) % cbQueue, 

and if overflow occurs, the new head is positioned by: 
head = (tail + 1) % cbQueue, 
meaning the queue is full. 

Int21HookO is nearly ready for its copy loop, but first it 
clears the direction flag, then stores the limit address of 
the CQS buffer in EAX to be used inside the loop to detect 
wraparound. The next six instructions implement the copy 
loop. If the destination hits the limit address, it is reset to 
the beginning of the buffer, the MOVSB instruction does its 
thing, and the LOOP instruction loops back to the start of 
the loop until the byte count in ECX drops to zero. 

The ISR's last task is to notify teedll.dll that more data 
is ready. It first examines the CQSs flnHotify flag to see if a 
notify is already pending for the VM. If not, it sets the flag 
and calls NotifyClientO. NotifyClientO will clear the flag 
after the notification has been delivered. Since it is possi¬ 
ble for several notifications to be pending, and there is a 
limit to the number of callbacks that can be scheduled, 
flnNotify is used to coalesce multiple notifications into 
one. By the time teedll.dll finally gets the notification, 
there will just be more data in the queue to be read. 

The next half of wddjtee.asm implements the VxD's pro- 
tected-mode interface and client notification code. The 
function PMApiO was specified in the Decl are_Vi rtual_Device 
macro as the VxD's protected-mode interface function. A 
Windows program issues INT 2fh, function 1684h, with the 
VxD ID (in this case, 31B3h) in BX to obtain the address of a 
function (the protected-mode entry point) which, when 
called, will transfer control to PMApiO. It is up to PMApiO to 
define the register parameters (and perhaps stack-based 
parameters) used to communicate with the desired func¬ 
tion. A convention for VxDS is to use the AX register to 
hold a requested function number and to use register- 
based parameters (something DOS programmers are all 
too familiar with!). Whatever the DLL places in registers is 
available to the VxD via the CRS: similarly, the VxD returns 
values to the DLL by writing to the CRS. 

I have defined three API services in wddjtee.h (Listing 1): 
apiGetVersion, apiRead, and apiRegister. The DLL places one 


Acquiring a VxD ID 

Despite reports to the contrary (see Alex 
Shmidt's article in Andrew Schulman's 'Undocu¬ 
mented Corner,' p. 136 in the March '94 Dr. Dobbs 
Journal ), VxD IDs are very simple to obtain from 
Microsoft. You simply fill out the form letter Mi¬ 
crosoft provides, send it to vxdid@microsoft.com, and 
receive your 16-bit ID back within two weeks. In 
practice the turnaround can be as little as one day. 
Figure 2 is Microsoft's current form letter, which has 
changed somewhat from the one found in the sam- 
ples\vxdid.txt file of the DDK. □ 


Figure 2 Form letter for requesting a VxD ID 


Contact Name(s): 

Phone Number(s): 

Alt-Phone Number(s): 

Personal CompuServe Acct: 
Support Advantage Acct: 
Internet Email Address: 


Company Name: 
Address: 
City/State/Zip: 

Country: 
Company Phone: 

Company Fax: 
Company Email: 
Company CIS Acct: 


Number of VxD’s planned: _ 

Number of VxD ID requests enclosed: _[ 

Number of VxD ID’s assigned to your company so far: _ 

. Repeat following section for each VxD . 

VxD File Name: _.386 (Avoid using a V_D.386 name if possible.) 

Will this VxD be loaded from a TSR? (Yes/No) : _ 

Will this VxD call out to an MS-DOS device driver or 
TSR using Interrupt 2Fh. Function 1607? (Yes/No) : _ 

Please provide the estimated number of API's/Exports below. 

V86 functions : 

PM functions : 

VxD Services : 

If this VxD replaces a "standard" VxD. which one does it replace : _ 

Summarize the purpose of this VxD : 


Please provide a technical summary of this VxD below. (Please include for 
example, all interrupts hooked. I/O ports trapped, and memory trapped.) : 


In what way or with what products will this VxD be distributed? 


Will its API or Services be documented for other companies to call? 
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Listing 6 teedll.def —- Linker module definition file 

for teedll.dll 


teedll.def 

-- Linker nodule definition file for teedll.dll. 


LIBRARY teedl1 

DESCRIPTION 'TeeDlT 
EXETYPE WINDOWS 

CODE PRELOAD HOVEABLE DISCARDABLE FIXED 

DATA PRELOAD MOVEABLE SINGLE FIXED 

HEAPSIZE 4096 

EXPORTS 

WEP 81 RESIDENTNAME 


Listing 7 teeiist.c — Application displays DOS box 
stderr and stdout 



/* teeiist.c */ 

/* - Application displays DOS box stderr ( stdout. */ 
/* -- To build: */ 

/* cc -2 -d -DSTRICT teeiist.c teedll.llb */ 

♦Include <w1ndows.h> 

♦include <*indowsx.h> 

♦Include <string.h> 

♦Include "wddjtee.h" 

♦define cldEdlt 1 /* Edit control ID. */ 

char const szMalnClassC] = "TeeHaln": /* Hain class. */ 
char const szOutClass[] = "TeeOut"; /* Output els */ 
char const szTItleC] * "DOS Box Output"; 

LPSTR lprgch; /* Read buf. */ 

void AppendSztHUND hwnd, LPSTR lpsz, BOOL fShow): 

HURD HwndFIndHvmCHWND hwndOuner. DWORD hvm): 

LRESULT CALLBACK _export LwOutWndProcCHWND hwnd, 


BUG TRACKING 

TECHNICAL SUPPORT Made Easy 
With. 

for Windows™ 

Use TRACK to deliver a higher quality 
product in less time. TRACK has ready¬ 
made forms to enter Bug, System, and 
Customer information. It’s easy to setup 
and administer. 

TRACK has a powerful query and 
reporting facility, and automatic 
notification and change history to keep 
everyone informed. 

TRACK provides import, export and complete customization 
of forms, reports and views to meet the specific needs of your 
organization. 



SOFFRONT 

SOFTWARE 

1806 Milmont Dr., #169 
Milpitas, CA 95035 
Ph: (408) 263-2703 
Fax: (408) 263-7452 



30 day, unconditional money-back guarantee! 


□ Request 201 on Reader Service Card □ 


of these values into AX before calling the protected-mode 
entry point. When PMApiO gains control, it examines the AX 
register in the CRS, and calls one of three service functions 
to handle the request. If the function number passed to 
PMApiO is within the range of legal function numbers, 
PMApiO jumps through a lookup table (rgpfn) to the appro¬ 
priate function. The simplest of these functions is UGetVer- 
sionO, which is called when the CRS s AX contains 
apiGetVersion. This routine copies the version constant into 
the CRSs AX register, and its job is done. Nearly as simple 
is RegisterLpfnO, which is called when the CRSs AX con¬ 
tains apiRegister. In this case the VxD expects teedll.dll 
to pass the address of a callback function via ES:DI. The 
16:16 address is extracted from the CRS and stored in the 
global variable lpfnNotify. It is this function that will be 
called by NotifyClientO. 

The most complicated service routine is CchReadO, which 
handles requests to read the contents of the CQS for a given 
VM. This routine expects DX.-BX to contain the VM handle, 
DS:SI to be the address of the buffer to receive the data, and 
ES:DI to be a pointer to a flag to set in case of overflow. 
CchReadO will return the number of bytes copied in AX. 

CchReadO begins by writing 0 to the CRSs AX register in 
case of failure. It then extracts the VM handle from the 
CRSs DX-.BX register pair and calls PcqsFindHvmO to find the 
CQS node. If either the VM handle is invalid or no CQS node 
could be found, the routine exits. CchReadO then writes the 
contents of the CQSs overflow flag to the location given by 
the flag pointer passed via £5:0/ (in the CRS). The number 
of bytes in the queue is then obtained, and if there are 
none, the routine exits. Since CchReadO also uses the M0VSB 
instruction, it sets up ES:EDI to address the destination 
buffer and ESI to address the head of the queue buffer. It 
then writes the new head position back to the CQS, calcu¬ 
lates the limit address of the queue buffer to test for wrap 
inside the loop, and clears the direction flag. 

The loop is just like the one in Int21Hook(), except that 
this time data is being read from the queue buffer. If the 
source address hits the limit, it is reset back to the start of 
the buffer. The loop terminates once all the bytes have 
been copied and ECX goes to zero. 

The last part of the VxD contains the notification code. 
NotifyClientO first checks if a client callback has been reg¬ 
istered, and exits if not. NotifyClientO is always called 
from a VM other than the system VM. Before the callback 
in the system VM can be called (UddjTeeNotifyProcO), a 
context switch must occur to the system VM. NotifyCli¬ 
entO therefore schedules a context switch to the system 
VM and specifies a routine, DoNotifyO, to be called after 
the switch has been made. The VMM routine CallJMJvent 
performs the scheduling, and accepts a 32-bit user-defined 
value that will be passed to DoNotifyO via the EDX regis¬ 
ters. For my purposes, notifications require both a VM 
handle (32 bits) and notification code (16 bits). To avoid 
allocating memory to hold the notification data (a global 
cannot be used since this service is asynchronous), I de¬ 
cided to pack the VM ID (the number of the VM, with the 
system VM starting at 1) and the notification code into a 
32-bit value. This allows for up to 65536 concurrent VMs, 
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C CODE FOR THE PC 

source code, of course 

Graphic 7.0 (high-resolution, scientific plots in color & hardcopy, contour plots, device independence).$370 

X/DOS and Xt/DOS (Xlib with X client and Xt toolkit for DOS; port X code to DOS; Xt/DOS r equ ires X/DOS and 32-bit compiler) . . each $300 
ZIP Image Processor & Victor Image Library Version 2.2 (brightness, contrast, merge images, TIRF/GIF/PCX/bin, HP ScanJet support) . . $290 
TE Editor Developer’s Kit for Windows V3.5 (full screen editor, undo command, word processing; TER for application build-in; no royalties) $280 
C/C+ + Libraries by Code Farms (persistent C structures, ER models, dynamic arrays, database functions, Jolt Award winner, specify Cor C++)$250 

TirboTgX (Release 3.0; HP, PS, dot drivers; CM fonts; LaTgX; MetaFont).$250 

Rogue Wave tools.h++ or math.h++ Class Library (extensive docs; DOS only; Windows $315 each).each $240 

Crusher! V200 (platform-independent data compression for network transfer; beats PK & LH on binary; directory trees; portable C) ... . $215 

COMM-DRV (complete interrupt-driven serial communication libraries & device drivers; full source).$155 

TE Editor Developer’s Kit Ver. 3.0 (full screen editor, undo command, multiple windows; with Word Processing $230).$155 

Minix Operating System (Version 1.5; Unix-like operating system, includes manual; specify 5.25” or 3.5” diskettes).$150 

XASM (cross assemblers & utility programs; 65xx, 68xx, 80xx; Intel or Motorola hex format; macro preprocessor).$150 

Delorie GCC for MS-DOS (Version 222; includes C+ +, assembler, DOS extender, 387 emulation; complete source code and makefiles) . . $150 
Moby Crypto (PGP, DES, Secure Hash, UFC, MDs, Crack 4.1, Lucifer, IDEA, VCR+, large integer packs, tutorials, more; not for export) . . $150 

Lisp for DOS (Kyoto Common Lisp and CLISP; KCL includes Lisp-to-C translator for building mixed Lisp/C programs) .$140 

Ibrow (Version 4.1; programmer’s Windows-based editor; large files, help, undo/redo, drag-n-drop, function & type tags).$135 

Updated! SCM (portable Scheme in C, IEEE standard, includes JACAL symbolic math package; SCM-4D0/SLIB-1D5/JACAL-1A3) .$100 

PC/IP (CMU/MIT TCP/IP for PCs; Crynwr drivers, NFS server, Bdale mailer, PCRoute/PCBridge, NDIS/ODI drivers, Beholder, more) . . . $100 

DA (disassembler for Microsoft’s New Executable (NE) binary files including Windows .exe, .drv, .dll, and .fit).$95 

Script Interpreter (a command script interoreter for DOS-based systems; C-fike script language; lots of features).$90 

CELP 3.2c (Federal Standard 1016 Code Excited Linear Predictive voice sampling and encoding; voice over 4.8Kbps; Unix code).$80 

CPPCOMM (C+ + serial communications class library for DOS, Windows, OS/2 and NT; includes X/Y/Zmodem).$75 

ETNeural Net (back error propagation and Kohonen).$75 

FlexList (doubly-linked lists of arbitrary data with multiple access methods; specify C or C++).$65 

Kier DateLib (all kinds of date manipulation; translation, validation, formatting, & arithmetic).$60 

Coder’s Prolog (Version 3.0; inference engine for use with C programs).$60 

Updated! PCCTS Version 1.10 (Purdue Compiler Construction Tool Set; like YACC and LEX together with lots of additional features).$60 

Container Lite V 1.82 (C+ + & FLC wrapper emulators; portable, persistent containers of arbitrary data including pointers).$50 

BigFloat (arbitrary precision floating point arithmetic and functions; includes BCD conversion).$50 

EZCalc (ASCII algebraic expression evaluator, unlimited parenthesis nesting, symbols, 32 built-in functions, easily extended).$50 

Backup & Restore Utility by Blake McBride (multiple volumes, file compression & encryption)..$50 

CUPS Version 6.0 (rule-based expert system generator; Windows compatible; manuals on disk).$50 

SuperGrep (exceptionally fast, revolutionary text searching algorithm; also searches sub-directories).$50 

OBJASM (convert .obj files to .asm files; output is MASM compatible) .$50 

Editor Pack (20 public domain editors; micromacs 3.12, Stevie, Elvis, Moke, mg2a, DTE, Jove, Origami, CE & GRIEF).$50 

Exceptions for C (Ada-like exception handling for C programs; exceptions for any block; exceptions can be reraised).$45 

DES Encryption & Decryption (2500 bits/second on 4.77 MHz PC for on-the-fly encryption at 2400 baud; not for export).$40 

Database Pack (9 databases - simple to complex: isam, bplus, AVL, SDB, ID, gdbm, Requiem, Ingres89, Postgres).$35 

COP (poor man's C++; C macro package which implements C++in C) .$35 

OCT (Object C Translator; essentially Brad Cox's Objective-C Version 4) ...$35 

RXC & EGREP Version 20 (Regular Expression Compiler and Pattern Matching; finite state machine from regular expression).$35 

Bison & BYACC (YACC workalike parser generators; documentation; includes Cand C+ + grammars) .$35 

Spell Pack (6 spelling programs, a hyphenator, 2 utility packs and a 60K word list: Ispell, Microsp, Sp, Cspella, Spell, Dawg, Soundex) .... $30 

REGX Plus (Version 3.0, search and replace string manipulation routines based on compiled regular expressions).$30 

GNU Awk & Diff for PC (both programs in one package).$30 

Big Number Pack (7 arbitrary precision arithmetic packages in C, one in Fortran but free Fortran-to-C converter is included) .$30 

Crunch Pack (30 file compression & expansion programs; now includes portable ZIP).$30 

NE W! OORT (C++ ray tracing code from the book by Nicholas Will) .$30 

OEmacs (full GNU Emacs for DOS and Windows DOS box; C+ + support, elags++, lots of .el files) .$25 

CTa>k Version 2.22d (robust MS-DOS multitasking kernel; C functions run as light-weight processes; mailboxes, interrupts, pipes, etc.) . . . $25 

PERL for MS-DOS (Version 4.019; C, sed, awk, and shell all rolled into one language; includes hardcopy docs).$25 

FLEX Version 2.4.3 (fast lexical analyzer generator; new, improved LEX).$25 

GNU RCS (FSFs version of the Revision Control System; like Unix’s SCCS only better; keeps track of software development).$20 

Data 

Moby Thesaurus II (6,000 root words, 2.5M synonyms, ’’common sense", concept related searches) .$500 

Moby Pronunciator II (175,000 words & phrases encoded with full IPA pronunciation & emphasis points).$265 

Moby Part-of-Speech II (230,000 words and phrases described by prioritized part(s)-of-speech).$170 
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a limit I'm not worried about being reached. Call_VM_Event 
expects the handle of the VM to switch to (in this case, 
the system VM) to be in EBX, a job conveniently accom¬ 
plished with the VMM function Get_Sys_VM_Handle. 

Some time after the context switch to the system VM 
has occurred, the VMM invokes DoNotifyO. DoNotifyO calls 
the callback whose address is in the global variable 


lpfnNotify using the following macros and services: 
Push_Client_State, Begin_Nest_Exec, Simulate_Far_Call, Re- 
sume_Exec, End_Nest_Exec, and Pop_Cl i ent_State. Be- 
gin_Nest_Exec and End_Nest_Exec are the VMM services used 
to delineate a nested execution block. Within such a block 
any changes to the machine's registers are reflected in the 
VM's CRS, so the contents of the CRS should be saved just 


Listing 7 continued 


HINT Ml, WPARAM wParam, LPARAM IParam); 

LRESULT CALLBACK _export LwMainHndProcCHWNO hwnd, 

HINT mu. WPARAM wParam, LPARAM IParam); 

int PASCAL WinMainIHINSTANCE hlns, HINSTANCE hinsPrev, 
LPSTR lpsz, int wShow) 

/ ***************************************************** / 
/* -- Entry point. */ 

/***************************************************** / 
{ 

HWND hwnd; 

MSG msg; 

if (NULL == hinsPrev) 

{ 

WNDCLASS WCS; 
wcs.style = 0; 

wcs.lpfnWndProc = LwMainWndProc; 
wcs.cbClsExtra = 0; 
wcs.cbWndExtra = 0; 
wcs.hlnstance = bins; 

wcs.hlcon = LoadlconCNULL. IDI.APPLICATION); 
wcs.hCursor = LoadCursor(NULL, IDC_ARR0W); 
wcs.hbrBackground = (HBRUSH)(C0L0R_WINDOW + 1); 
wcs.lpszMenuName = NULL; 
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wcs.lpszClassName = szMainClass; 
if (!RegisterClass(4wcs)) 
return FALSE; 

wcs.lpfnWndProc = LwOutWndProc; 
wcs.cbWndExtra * sizeof(DWORD); 
wcs.lpszClassName = szOutClass; 
if (!RegisterClass(&wcs)) 
return FALSE; 

} 

if (NULL == (lprgch = Global AllocPtr(GMEM_MOVEABLE, 
(long)cbReadMax + 1))) 
return FALSE; 

msg.wParam = 0; 

if (NULL != (hwnd = CreateWindow(szMainClass, 
szTitle, WSJVERLAPPEDWINDOW, CWJSEDEFAULT. 
CWJSEDEFAULT, CWJSEDEFAULT. CWJSEDEFAULT. 

NULL. NULL. hins. NULL))) 

{ 

ShowWindow(hwnd, wShow); 

while (GetMessage(4msg, NULL, 0. 0)) 

{ 

TranslateMessageUmsg); 

DispatchMessage(imsg); 

} 

) 

GlobalFreePtr(lprgch); /* No need, really. */ 
return msg.wParam; 

} 

LRESULT CALLBACK _export LwMainWndProc(HWND hwnd. 

UINT wm. WPARAM wParam, LPARAM IParam) 
/*****************************************************/ 
/* -- Main window procedure. */ 

/*****************************************************/ 

{ 

HWND hwndT; 

RECT rect; 
char szBuf[32]; 

switch (wm) 

{ 

default: 

break; 

case WMJREATE: 

FRegisterWnd(hwnd); 

break; 

case WMJESTROY: 

FUnregisterWnd(hwnd); 

PostQuitMessage(0); 

break; 

case wmVMCreate: 

GetClientRect(hwnd, &rect); 

ClientToScreen(hwnd. (LPP0INT)4rect); 
wsprintf(szBuf. "VM 0xXlx", IParam); 

CreateWi ndow( szOutCl ass, szBuf, WSJAPTION I 
WS_POPUPWINDOW I WS.THICKFRAME | WSJISIBLE, 
rect.left, rect.top. rect.right, rect.bottom, 
hwnd. NULL, GetWindowInstance(hwnd), 

(LPVOID)IParam); 
return 0; 

case wmVMDestroy: 
if (NULL != 

(hwndT = HwndFindHvm(hwnd. IParam))) 
DestroyWindow(hwndT); 
return 0; 

case wmDataReady: 
if (NULL != 

(hwndT = HwndFindHvm(hwnd, IParam))) 
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before entering the block and restored just after leaving it. 
The macros Push_Client_State and Pop_Client_State per¬ 
form this service. The VMM service Simulate_Far_Call sets 
up a call to the callback, which occurs by the time Re- 
sume_Exec has been executed. 

After saving the CRS, DoNotifyO extracts the notification 
code and VM ID from EDX. The VMM Simulate_Push service 
is used to push a 16-bit argument (the contents of AX) 
onto the client's (teedll .dll's) stack, in this case the notifi¬ 
cation code. The utility routine PcqsFindVmiO is called to 
return the COS node for the given VM ID. PcqsFindVmiO is 
identical to PcqsFindHvmO except that it's the vmi member 
(virtual machine ID) that is compared against EBX, rather 
than the hvm member. 

DoNotifyO then checks if this is a nfcDataReady notifica¬ 
tion; if so, it clears the COSs flnNotify flag, since the notifi¬ 
cation will have occurred by the time DoNotifyO has re¬ 
turned. The VM handle is then extracted from the CQS and 
pushed one-half at a time onto the client's stack. DoNo¬ 
tifyO next checks if the notification is nfcVMDestroy, in 
which case, as mentioned earlier, it will unlink and deallo¬ 
cate the CQS node. Finally, the callback is made using Simu- 
late_Far_Call and Resume_Exec. 

wddjtee.386 can be built using the linear linker defini¬ 
tion file, wddjtee.def, in Listing 3 and the makefile in List¬ 
ing 4. The line 'device=wddjtee.386' needs to be added to 
the [386Enh] section of your system.ini to load the VxD at 
startup. A convenient place to put the wddjtee.386 file is in 
your SYSTEM subdirectory. 


Listing 7 continued 


SendMessage(hwndT, i 
return 0; 

} 


0 . 0 ); 


return DefWindowProc(hwnd, wm, wParam, lParam); 

} 

HWND HwndFindHvm(HWND hwndOwner, DWORD hvm) 

/* -- Return the owned popup for the given VM. */ 
/*****************************★*******★*****★********* / 
{ 

HWND hwndT; 
char szBuf[32]: 

for (hwndT = GetWindow(hwndOwner, GW_HWNDFIR$T); 
NULL != hwndT; 

hwndT = GetWindowChwndT, GW_HWNDNEXT)) 

{ 

GetClassName(hwndT, szBuf, slzeof(szBuf) - 1); 
if (!lstrcmp(szBuf, szOutClass) && 

(DWORD)GetWindowLong(hwndT, 0) == hvm) 
return hwndT; 

} 

return NULL; 

} 

LRESULT CALLBACK _export LwOutWndProc(HWND hwnd, 

UINT wm, WPARAM wParam, LPARAM lParam) 



LPVOID lpv; 

UINT cchEdit, cchRead; 
long cchT; 

HWND hwndEdit; 

BOOL fOver = FALSE; 

switch (wm) 

{ 
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Listing 7 continued 


default: 

break; 

case WM_CREATE: 

SetW1ndowLong(hwnd, 0. (DWORD) 

((LPCREATESTRUCT)lParam)->1pCreateParams); 

If (HULL == 

(lpv = G1obalA11ocPtr(GHHD. 0x00010000))) 
return -1; 

If (NULL == (hwndEdit = CreateWindowCedit". 
NULL, WS.CHILD I WS.VISIBLE I WSJSCROLL | 
WS_HSCROLL | ES_MULTILINE I ES.READONLY, 

0, 0. 0. 0. hwnd. (HHENU)cidEdit, 

(HINSTANCE)SELECTOROF(lpv). NULL))) 

{ 

GlobalFreePtr(lpv): 
return -1; 

} 

SendMessageChwndEdit. EM_LIMITTEXT, 0. 0); 
SendMessage(hwndEdit. WMJETFONT, 
(WPARAM)GetStockObject(0EM_FIXED_F0NT). 0): 
break; 

case WM_SIZE: 

SetWindowPos(GetDlgItem(hwnd, cidEdit), NULL, 
0, 0, LOWORDdParam), HIWORDdParam), 
SWPJOACTIVATE | SWPJOMOVE | SWPJOZORDER): 
break: 

case wmDataReady: 

hwndEdit = GetDlgItern(hwnd, cidEdit): 
cchEdit = (UINT)SendMessage(hwndEdit, 
WM_GETTEXTLENGTH, 0. 0): 
cchRead = CchReadHvm(GetWindowLong(hwnd. 0), 
Iprgch, ifOver); 

If (dong)cchEdit + cchRead > 0x8000) 

{ 

SendMessage(hwndEdit. WMJETREDRAW. FALSE. 
0 ): 

cchT = cchRead + cchEdit - 0x8000: 
if (cchT > 0xffff) 


The DLL 

The counterpart of wddjtee.386 is teedll.dll, imple¬ 
mented by teedll.c in Listing 5. The DLL isolates the 
somewhat arcane interface to the VxD, so that client tasks 
of the DLL encounter only a nice, simple interface. The 
interface is defined by the bottom half of wddjtee.h (Listing 
1). It includes three API functions and three notification 
messages. The client task calls FRegisterhlndO with the 
handle of the window that is to receive notification mes¬ 
sages. The notification messages are just the nfc notifica¬ 
tion codes with the constant UM_USER added. Each notifica¬ 
tion will contain the corresponding VM handle in the 
7 Param parameter. 

When the client no longer wishes to receive notifica¬ 
tions, it calls FUnregisterUndO. In response to a wmDataReady 
notification message, the client may wish to call the last of 
the API functions, CchReadHvmO. This function accepts the 
handle of the VM to read, a far pointer to a 64Kb buffer 
to hold the data, and a far pointer to a flag that will be 
set by CchReadHvmO if overflow has occurred since the last 
read. The routine returns the number of bytes actually 
read. 

The DLL's LibMainO starts out by obtaining the address 
of wddjtee.386s protected-mode entry point. It is actually 
the VMM that handles this request, and instead of return¬ 
ing the 16:32 address of PMApiO (which would be awkward 
to deal with using 16-bit code), it returns the address of an 
INT 30h instruction in a private kernel code segment 
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(known as a 'protect mode break point'). Calling this 
breakpoint transfers control to the VMM through a 32-bit 
interrupt gate. The VMM in turn transfers control to the 
wddj tee. 386s PMApiO function. 

The protected-mode entry point is obtained through 
the multiplex interrupt (2Fh), using function number 1684h 
and specifying the VxD ID (31B3h) in BX. The entry point is 
returned in the ES-.DI register pair. If this fails, indicating 
that the VxD is not present, LibMainO returns FALSE, 
thereby aborting the loading of the DLL. The address of 
the protected-mode entry point is stored in the global vari¬ 
able lpfnVxD. LibMainO then calls through lpfnVxD, placing 
the function number apiGetVersion in AX, to obtain the ver¬ 
sion number of the DLL. If it is less than the version num¬ 
ber the DLL was built for, LibMainO 
fails. Lastly, LibMainO registers the ad¬ 
dress of its notification callback with 
uddjtee.dll by specifying the function 
number apiRegister in AX and the ad¬ 
dress of the callback in ES-.DI (a con¬ 
vention imposed by wddjtee.386). 

It is extremely important to unreg¬ 
ister the callback function before the 
DLL is unloaded (failure to do this 
would result in the VxD calling to a 
non-existent Windows function, a de¬ 
cidedly unhealthy situation), so a 
UEPO function is required. The UEPO 
goes through the same motions as 
the LibMainO code to register the call¬ 
back function, except that it passes 
NULL for the address. 

The next function, FRegisterUndO, 
sets the given window handle into 
the global hwndClient variable. How¬ 
ever, if the variable has already been 
set (a client has already been regis¬ 
tered), the procedure fails. FUnregis- 
terUndO is just as simple. If the win¬ 
dow handle to unregister is the same 
as that of the current client, hwndCli¬ 
ent is reset to NULL, and the proce¬ 
dure succeeds. Otherwise, the win¬ 
dow is not a client, and the proce¬ 
dure fails. 

Next is UddjTeeNotifyProcO, which 
was registered as the DLL's callback 
function back in LibMainO. This rou¬ 
tine merely adds UM_USER to the notifi¬ 
cation code, then forwards it to the 
client window with PostMessageO. 

The last function in teedll.c is 
CchReadHvmO. It consists of some inline 
assembly glue to load the appropri¬ 
ate registers before calling through 
lpfnVxD with the apiRead function 
number in AX, and some more glue 
to return the character count. 


Listing 7 continued 


cchT = 0xffff; 

SendMessage(hwndEdit, EMJETSEL. 0. 
MAKELONG(0, cchT)); 

SendMessage(hwndEdit. EM_REPLACESEL, 0. 
(LPARAMKLPSTR)""); 

SendMessage(hwndEdit, WH_SETREDRAW, TRUE. 

0 ); 

} 

lprgch[cchRead] * 0; 

If (fOver) 

AppendSz(hwndEdit. 
"\r\n***Overflow***\r\n", FALSE); 
AppendSzChwndEdit r lprgch, FALSE); 

AppendSz(hwndEdit. HULL. TRUE); 
return 0; 

} 
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teedll.dll is built using the module definition file 
teedll.def in Listing 6. The only reason a .def file is re¬ 
quired (normally, the cc utility, available with W/DDJ's 
electronic code distribution, would take care of this detail) 
is that l need to make the DLL's code segment FIXED. I 
could do this with code (GlobalPageLockO), but the result 
will be the same, since GlobalPageLockO will relocate the 
code segment low and lock it down, just as declaring it 
FIXED in the .def file does (this applies only to DLLs). 

The Demo Application 

teelist.exe (implemented with teelist.c in Listing 7) is 
a sample program that demonstrates the use of 
teedll.dll. The application consists of a main window that 
creates a new popup window each time it receives a 
wmVMCreate notification message. The popup contains a 
multi-line edit child window that is used to capture output 
from the VM. The main window receives notifications, 
routing mDataReady messages to the associated popup win¬ 
dow. When the main window receives a wmVMDestroy mes¬ 
sage, it finds the associated popup and destroys it. 

teelist.c begins with the usual UinMainO function. Uin- 
MainO registers a class for the main window, and another 
for the popup windows. The popup window class specifies 
an extra window long for storage of the VM handle. Uin¬ 
MainO then allocates a 64Kb block of memory to use as 
the buffer when calling CchReadHvmO. It creates its main 
window, enters a message loop, and frees the 64Kb mem¬ 
ory block before exiting. 

The main window procedure, LwMainUndProcO, registers 
itself with teedll.dll when the window is created (UM_CRE- 
ATE), and unregisters itself when the window is destroyed 
(UM_DESTROY). When a wmVMCreate notification message is re¬ 
ceived, it creates a popup window that just fills the client 
area. The IParam, which contains the VM handle, is passed 
to CreateUindowO via the lpvParam parameter, so that it can 
be passed to the popup window procedure during crea¬ 
tion. The wmVMCreate case also sets the title of the popup 
window to be the VM handle of the VM being monitored. 

When LwMainUndProcO receives a wmVMDestroy notifica¬ 
tion, it calls the utility function HwndFindHvmO to locate the 
popup window associated with the VM handle and 
DestroyUindowO to destroy it. The last message handled by 
LwMainUndProcO is wmDataReady. It uses HwndFindHvmO to find 
the popup for the VM handle in IParam, and forwards the 
message to the popup with SendMessageO. 

HwndFindHvmO uses a GetUindowO loop, starting at the 
first top-level window with GetUindowfhwndOwner, 
GU_HUNDFIRS1) (both popup windows and overlapped win¬ 
dows are top-level windows). It iterates over the top-level 
windows until it encounters a window that belongs to its 
registered popup class and has the given VM handle in its 
window extra long. 

The next function is the window procedure for the 
popup output windows, LwOutUndProcO. At UM_CREATE time, 
the procedure extracts the VM handle from the 
LPCREATESTRUCT and stores it in the window's extra long. It 
then allocates a 64Kb buffer to be used as the multi-line 
edit window's text buffer. This is accomplished by passing 


Listing 7 continued 


return DefHindowProc(hwnd, wm, wParam, IParaa); 

} 

void AppendSz(HWND hwnd, LPSTR Ipsz. BOOL fShow) 

I* -- Append the given string to the edit control. */ 
{ 

UINT cch; 
cch = 

(UINT)SendMessage(hwnd, WM_GETTEXTLENGTH, 0. 0); 
SendMes sage (hwnd. EMJETSEL, fShow ? 0 : 1. 

MAKELONGCcch. -1)); 

If (NULL != Ipsz) 

SendMessage(hwnd, EM_REPLACESEL, 0, 
(LPARAM)lpsz); 

} 

/* End of File */ 


in the selector to the memory (the high word of the ad¬ 
dress returned from GlobalLockO'mg the handle) as the 
hinst parameter to the CreateUindowO call for the edit. By 
default, an edit is created with a text limit of 32Kb. This 
limit must be explicitly overridden by sending an EM_LIMIT- 
TEXT to the edit to allow the full 64K characters. 

LwOutUndProcO then sets the edit window's font to the 
stock 0EM_FIXED_F0NT, which is what Windows uses to dis¬ 
play text in a windowed DOS box. This ensures that OEM 
graphics characters are properly displayed in the edit. The 
edit window is created with an initial size of 0, but the 
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code in the UMJIZE message ensures that the edit window 
will fill the popup's client area. 

The code that handles the wmDataReady message is re¬ 
sponsible for reading into the edit window the data that 
the VxD has accumulated for the VM. My goal here was 
really to keep the code to a minimum, so there is lots of 
room for improvement. As written, the data is read into 
the 64Kb buffer allocated during initialization, and if the 
length of the data read from the VxD plus the length of 
the data already in the edit exceeds 32Kb, then sufficient 
data at the start of the edit is removed to allow the new 
data to be appended. You might wonder at the choice of 
32Kb. By experimenting, I discovered that when the edit 
already contained 32Kb of data, it was incapable of stor¬ 
ing an additional 16Kb. It would call LocalAllocO to ex¬ 
pand its text buffer, and the call would fail, even though 
the local heap is in a 64Kb global block. The edit control 
must be claiming some other large block of local memory 
in addition to its text buffer, perhaps for an undo buffer 
(although attempts at sending the EM_EMPTYUNDOBUFFER be¬ 
fore appending text to the edit did not help the situation). 
In any case, a multi-line edit is not a good choice for a 
monitor window, especially if you want to buffer the out¬ 
put: it can only hold a theoretical limit of 64Kb, and its 
programmatical interface does not lend itself well to im¬ 
plementing a scrolling data window. If you will be imple¬ 
menting DOS output monitoring in a commercial applica¬ 
tion, I suggest investing the time in writing a custom scrol¬ 
lable text control. 


The wmDataReady code deletes text from the start of the 
buffer by first selecting the text with an EM_SETSEL mes¬ 
sage, then replacing the selection with an empty string 
with the EM_REPLACESEL message. It turns redrawing off 
(with UM_SETREDRAU) around the operation to prevent the 
edit from scrolling to the start of its text. After the selected 
text has been deleted, UM_SETREDRAU is sent once again to 
the edit, this time to re-enable drawing. 

The remainder of the code uses the utility function Ap- 
pendSzf) to append the new string to the end of the edit's 
text. This function places the beginning and end of the 
selection at the end of the last character in the edit, i.e., 
the selection is set to the insertion point. The EM_REPLACESEL 
message is then used to replace this empty selection with 
the text to append. AppendSzO accepts an additional pa¬ 
rameter, fShow, which tells it whether or not to scroll to the 
end of the newly appended text. If it is set, then the 
EM_SETSEL's wParam is set to 0, which causes the new selec¬ 
tion to be scrolled into view; otherwise, wParam is set to 7, 
which prevents the edit from scrolling. 

If the fOver flow flag is set as a result of the wmDataReady 
code's call to CchReadHvmO, the text "‘“Overflow***" is ap¬ 
pended to the edit text. The text obtained from 
CchReadHvmO is inserted, and a final call is made to Ap¬ 
pendSzO, this time with no string but with the fShow flag set 
to TRUE to scroll the end of the text into view. 

Problems with Multiple VMs 

While I was writing and debugging the code in this arti¬ 
cle, I noticed some interesting DOS VM behavior that is 
related to wddjtee.386. Try this experiment (your results 
may vary, I was working on an 80486, 25MHz machine): 
with no other applications running, create two windowed 
DOS boxes. Minimize program manager and tile the DOS 
boxes. Type 'dir' in one, click on the other, and type 'dir 
in that one (this works best when the current directory in 
each contains a lot of files, such as your WINDOWS direc¬ 
tory). If you look closely, you will see that each DOS box 
drops characters from every tenth file (or so). 

My first reaction when I saw this was 'Oh no, 
wddjtee.386 is breaking something!' So I removed the 'de- 
vice=wddjtee.386' line from my system, ini and tried it 
again. Same problem. After thinking about this a bit, I re¬ 
alized that Windows is doing essentially the same thing as 
wddjtee.386 and teedll.dll. The dir command is running 
merrily away inside the DOS VM. But it is UinOldAp that is 
responsible for actually displaying the text in the DOS win¬ 
dow, (using ExtTextOutO, by the way). The only way for 
this to work is for Windows to context-switch like mad 
between the DOS VM, so it can run the dir command, and 
the system VM, so UinOldAp can display the results. But the 
communication between the two is asynchronous, due to 
the nature of the protected-mode interface. This means 
that if ExtTextOutO (combined with scrolling) is slow, Ui¬ 
nOldAp may not be able to keep up with the DOS VM, and 
the result will be lost characters. You can expect similar 
difficulties with tlist.exe. Monitoring too many active DOS 
VMs will result in overflow. □ 
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Windows Multimedia: Part 3 
Blocks Effect and Palette 
Fade-In 

Charles Mirho 



Borland C++ v4.0 
Symantec C++ v6.1 
Visual C++ vl .5 


In Part 2 of this series, I looked at how bitmaps can be 'spiraled' into a 
window. This month I examine the final bitmap special effects in the series, the 
blocks effect and the palette fade-in. The blocks effect displays the bitmap as a 
series of pseudo-random blocks which fill in like the pieces of a puzzle. The 
palette fade-in displays progressively more color content from the bitmap, mak¬ 
ing it appear to fade into the window. 

As with the other special effects discussed in this series, these effects assume 
the bitmap is already loaded in memory, typically from a disk file. The sample 
program on the code disk (see Online Source Code box on table of contents for 
availability) contains code to do just this. It is also assumed that a device-inde¬ 
pendent header, a display context, and a logical palette have been set up for 
the bitmap. These are standard techniques which have been covered in other 
articles, and so will not be repeated here. 

How to Create a Blocks Effect 

In the blocks effect, blocks of pixels are chosen 'randomly' from the bitmap 
for display. The bitmap is displayed as though it were a puzzle being assem¬ 
bled within the window, a piece at a time, in more or less random order. To 
accomplish this, I use a pseudo-random number generator to generate the 
block coordinates. The random generator is carefully chosen to create what is 
known as a pseudo-noise sequence, that is, a sequence of numbers that cycles 
through a fixed range without replacement (without duplicating values). The 
code to implement the blocks effect is in blocks, c (Listing 1). 


Charles Mirho is a consultant specializing in Multimedia and Telephony. He holds a 
Master's degree in Computer Engineering from Rutgers University. He can be reached 
on CompuServe at: 70563,2671. 
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The pseudo-noise generator works by taking any sev¬ 
enteen-bit number, called the seed value, and shifting it 
one bit left upon each iteration of the loop. The seed 
value can be any number within the range 0 to 2 17 -1. 
Each time the value is shifted, the 


number of blocks that can fit across the width of the bit¬ 
map. The number of rows in the array is the number of 
blocks that can fit down the height of the bitmap. Thus I 


least significant bit is filled with either 
a one or a zero. Whether the fill bit 
is a one or a zero depends on the 
values of certain other bits, called the 
tap bits, in the number. An odd num¬ 
ber of tap bits means fill with a one, 
and an even number of tap bits 
means fill with a zero. Figure 1 
shows the placement of the tap bits 
for a maximal-length, 17-bit pseudo¬ 
noise generator; maximal length 
means it generates the greatest num¬ 
ber of unique values in the range, in 
this case 2 77 - 7 values. 

The random generator terminates 
when the seed value is repeated. 
This will only occur when ail other 
values in the range have been gener¬ 
ated. To compute an x, y coordinate 
at which to display the next block, I 
take the randomly generated value 
and convert it into the index of a 
two-dimensional array. This array has 
a number of columns equal to the 
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Listing 1 blocks, c — Code to implement random block effect 


//define BIT0 0x00000001 

//define BIT2 0x00000004 

//define BIT15 0x00008000 

//define BIT16 0x00010000 

//define BIT17 0x00020000 

//define SEQ (BIT17) 

/************************************************************************** 

* Function Name: bmpBlocks 

It*************************************************************************/ 

int bmpBlocks (HDC hDC, BITMAPINFO *p_binfo, LOGPALETTE *p_paL BYTE _huge *hp_bits, 

HDC hjnemDC, HBITMAP h_bmp, HPALETTE h_pal) 

{ 

unsigned long seed; 
unsigned long value, maxvalue; 
unsigned long x, y. i; 

unsigned long fill. mask= (BIT16 I BIT15 I BIT2 I BIT0); 
unsigned long tmp, cnt, shft; 

unsigned long width = p_binfo->bmiHeader.biWidth/BLOCK, 
height = p_binfo->bmi Header.bi Hei ght; 

/* maximum random value that is useful */ 
maxvalue = height/BLOCK* width; 
seed = SEQ-1; 

SetDIBits(hjnemDC, h_bmp, 0, (WORD)p_binfo->bmiHeader.biHeight. hp_bits, p_binfo, 
DIB_PAL_COLOR$); 

for (i=0, value=seed;;i++) 

{ 

fill = 0L; 

/* mask out randomize bits */ 
tmp = (value & mask); 

/* if the number of bits is odd, fill with a one */ 
shft = B1T0; 
cnt = 0; 

while (shft < SEQ) { 

if (tmp & shft) 
cnt++; 
shft «= 1; 

} 

if (cnt & BIT0) 

fill = BIT0; 

/* range and fill */ 
value «= 1; 
value 1= fill; 
value &= (SEQ-1); 
if (value == seed) 
break; 

/* discard value if out of range */ 
if (value > maxvalue) 
continue; 

/* compute x and y coordinates to display block */ 
y = (value/width) * BLOCK; 
x = (value % width) * BLOCK; 

BitBltthDC, (WORD)x, (WORD)y, BLOCK, BLOCK, hjnemDC, (WORD)x, (WORD)y, SRCCOPY); 

} 

/* fill 0,0 */ 

BitBltthDC, 0, 0, BLOCK, BLOCK, hjnemDC, 0, 0, SRCCOPY); 
return 0; 

) /* end function (bmpBlocks) */ 

/* End of File */ 
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first compute the width of the bitmap 
in blocks, and the height in pixels 

width = p_binfo->bmiHeader.biWidth/BLOCK; 
height = p_binfo->bmiHeader.biHeight; 

Then, for each value in the pseudo¬ 
random sequence, I compute the x 
and y coordinates at which to display 
the block as 

y = (value/width) * BLOCK; 
x = (value l width) * BLOCK; 

To compute the y (row) position at 
which to display the block, I divide 
the random value by the bitmap 
width in blocks. This gives the row 
position as a number of BLOCK units. 
To convert to pixels, this result is 
multiplied by the block height. The x 
(column) position at which to display 
the block is computed by taking the 
remainder of the division of the 
value by the bitmap width in blocks. 
This yields the column position at 
which to display the block in BLOCK 
units. Multiplying by the block width 
yields the column position for the 


Figure 1 Algorithm for generating random sequences 



Listing 2 fade.c — Code to implement palette fade effect 


/************************************************************************** 

* Function Name: bmpFade 

★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★♦★★★★★★★★★★★★★★★★★★■A;** j 

int bmpFade (HDC hDC, BITMAPINFO *p_binfo. LOGPALETTE *p_pal. BYTE Juge *hp_bits, 
HDC hjnemDC, HBITMAP h_bmp. HPALETTE h_pal) 

{ 

LOGPALETTE *p_fadepal; 

HPALETTE h_fadepal: 

WORD w_colors; 

int k; 

DWORD nextTime = GetTickCountO + 200; 
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block in pixels. Since I use a square block 4 pixels wide by 
4 pixels high, the number BLOCK is used for both the width 
and height of the block. 

With a block size of 4x4 pixels, the maximum size of a 
bitmap which can be displayed with this algorithm is 


Listing 2 continued 


/* make sure the driver supports palette animation */ 
if (!(RC_PALETTE & GetDeviceCaps (hDC, RASTERCAPS))) { 

MessageBox (NULL, "Palette Animation not Supported",”",HB_0K); 
return -1; 

} /* end if (palette animation not supported) */ 

/* compute number colors in image */ 
if (p_binfo->bmiHeader.biClrUsed != 0) 
w_colors = p_binfo->bmiHeader.biClrUsed; 

else 


(2 17 - 1) * 16 = 2 21 - 16 

or around 2 million pixels. This is twice as large as the 
resolution of a top-end graphics card, which can display 
1024x1024 pixels. Even bigger bitmaps can be handled if 
the block size is increased, say to 8x8. Almost any bitmap 
you encounter today can be dis¬ 
played using this effect, but it also 
means that for smaller, more com¬ 
mon bitmaps the random generator 
will create many out of range values. 
To remedy this situation, I check if a 
value is out of range for the bitmap 
at hand and immediately discard the 
value if it is: 

if (value > maxvalue) 
continue; 

where 



maxvalue = height/BLOCK * width; 

It is a good idea to check if the ran¬ 
dom value is within range before 
computing the x,y coordinates, thus 
saving CPU cycles. 

One final note: the random se¬ 
quence generator will never pass 
through zero, so the block at coordi¬ 
nates 0,0 must be specially filled 
once the algorithm terminates. 

Palette Fade 

The palette fade effect involves 
progressively revealing more and 
more of the color content of a bit¬ 
map. Since detail lies in the color, the 
image appears to fade in from very 
little detail to complete detail as 
more colors are added to the screen. 
The range of color in a bitmap is de¬ 
fined by the bitmap's palette, a table 
of RGB color codes which can be 
found in the bitmap's header area. 
Video hardware for computers also 
uses palettes to define the colors that 
are currently displayed on the moni¬ 
tor. Most video hardware today can 
display hundreds, thousands, or even 
millions of colors simultaneously - 
the actual number usually being a 
function of the screen resolution and 
the video memory available. Given a 
fixed amount of video memory, the 
higher the screen resolution, the 
lower the number of simultaneous 
colors which can be displayed. More 
resolution means more bits across 
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and down the screen, which takes up more memory. 
More simultaneous colors means more bits per color, 
which takes up more memory. 

Windows virtualizes the video hardware palette into 
something called the system palette; you can think of it as 
representing the video hardware palette. For a bitmap to 
be displayed in its true colors, the system palette must 
contain color entries corresponding to the colors in the 
bitmap palette. The palette fade effect only works on bit¬ 
maps with a palette; in the Windows environment, this 
generally means images with between 16 and 256 colors. 
Other restrictions to this effect are discussed in the conclu¬ 
sion. 

The key to the palette fade effect is a Windows func¬ 
tion called AnimatePaletteO. AnimatePaletteO can be used 
to directly change entries in the system palette. The same 
bits in the client area will produce drastically different col¬ 
ors, depending on the contents of the system palette. 
Think of it this way: you can use BitBltO to fill the client 
area with bits, then use AnimatePaletteO to change the 
color meaning of those bits without updating the client 
area. Given a bitmap displayed in the client area of a win¬ 
dow, if AnimatePaletteO is called to change the color en¬ 
tries in the system palette corresponding to the bitmap 
colors, the client area will change color. That is the crux of 
the palette fade effect. 

Suppose you have a 16-color bitmap. Once a logical 
palette is realized into a client area display context, the 
system palette contains entries for the colors of the bit¬ 
map. In Figure 2, I assume these colors in the system pal¬ 
ette are contiguous, although this may not be the case. 
Next, I call AnimatePaletteO : 

AnimatePalette(hPal,2,3,&pa1 NewColors); 

hPal is a handle to the currently realized logical palette for 
the client display context. The function tells Windows to 
replace three colors in the logical palette beginning at in¬ 
dex two with the new colors specified in the pal NewCol ors 
parameter. Figure 3 shows the replacement in the system 
palette. 

The bits assigned to these new color entries would 
then change color in the client area. Bear in mind that the 
Windows system palette is a complicated thing, and I 
have treated its discussion lightly here. A more thorough 
discussion of the Windows system palette may be found 
in other articles and texts on Windows. 

Before the palette effect can actually begin, some 
preparation is required. First, I make a copy of the logical 
palette that resides in the bitmap header. I copy all the 
static information, such as the palette version and number 
of colors, as well as the colors themselves, to a new pal¬ 
ette that I will modify; I call this copy of the original pal¬ 
ette the animation palette. After I create the animation 
palette, I set all of its colors to white, except for the first 
and last colors in the palette. 

The first and last entries in the palette correspond to 
the lightest and darkest colors in the bitmap, and I don't 
want to replace these with the color white. Why? Because 
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Listing 2 continued 


w_colors=(l « (p_binfo->bmiHeader.biBitCount*p_binfo->bmiHeader.biPlanes)); 

/* allocate animation palette */ 

if ((p_fadepal * (LOGPALETTE *)malloc (sizeof(LOGPALETTE) + 

(w_co!ors-1)*sizeof(PALETTEENTRY))) == NULL) 

{ return -1; 

1 //End if (error allocating palette) 

/* copy the image palette to the animation palette */ 

memcpy (p_fadepal. p_pal, (sizeof(LOGPALETTE) + (w_colors-l)*sizeof(PALETTEENTRY))); 

/* create the initial animation palette; all white except for the first and last entries, which 
are probably white and black */ 
for (k=l; k<(1nt)w_colors-1;k++) ( 

p_fadepal->palPal Entry[k].peGreen = 255; 
p_fadepal->palPalEntryik],peRed= 255; 
p_fadepal->palPal Entryik].peBl ue= 255; 
p_fadepal->palPalEntryCk].peFlags = PC_RE$ERVED; 

} 

/* grab the system palette entries */ 

UsePalette (hjnemDC, TRUE); 

/* realize the animation palette into the display context */ 
h_fadepal » CreatePalette (p_fadepal): 

SelectPalette (h_memDC, h_fadepal, FALSE); 

RealizePalette (h_memDC); 

/* blast up the bitmap - it will appear in only the limited colors of the animation palette */ 
SetDIBitsthjnemDC, h_bmp, 0, (W0RD)p_binfo->bmiHeader.biHeight, hp_bits, 
pjinfo, DIB_PAL_C0L0RS); 

BitBltthDC, 0. 0, (W0RD)p_binfo->bmiHeader.biWidth. 

(WORD)p_binfo->bmiHeader.biHeight, 
h_memDC, 0, 0, SRCCOPY); 


in a moment I am going to take over 
an area of the system palette called 
the system color area. This is the 
area of the system palette where 
Windows stores the colors that de¬ 
fine window title bars, borders, but¬ 
tons, and so on. When I take over 
the system color area, I need to pre¬ 
serve at least two colors of high con¬ 
trast, a very light and a very dark 
color, so that at least a monochrome 
rendition of window elements is vis¬ 
ible. Remember, all other colors in 
the animation palette have just been 
set to white. If the palette for the bit¬ 
map is really big, if it takes up most 
or all of the system palette, then only 
the first and last colors of the system 
palette will be left available to render 
window elements. 

I won't go into a detailed discus¬ 
sion of the system colors here. Suf¬ 
fice it to say that there are at least 
16 of them, and that, once changed, 
they must be restored to their origi¬ 
nal values, or else the Windows 
desktop will look really ugly. It is nec¬ 
essary to override the system colors 
to disable certain color mappings 
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that can ruin the effect. I use a func¬ 
tion called UsePaletteO to override 
and later restore the system colors. 
This function is from a sample pro¬ 
gram distributed by Microsoft. You 
can obtain the code from Com¬ 
puServe (GO MSL) by downloading 
file SI 4045; the function is also avail¬ 
able on the W/DDJ code disk (see the 
table of contents for availability). 

The code to implement the palette 
fade effect is in fade.c (Listing 2). The 
initial for loop sets all colors in the 
animation palette to white, except 
the first and last colors. Notice that 
the peFlags field of the PALETTEENTRY 
structure is set to PC_RESERVED, which 
tells Windows to that it is okay to 
change this value with Ani- 
matePaletteO. 

Next, I call UsePaletteO to grab 
the space reserved for the system 
colors, and call CreatePaletteO, Se- 
lectPaletteO, and RealizePaletteO to 
realize the animation palette into the 
bitmap display context and blast the 
bits to the client area. The bitmap 
will appear in only its very darkest 
and lightest colors - all other color 
content will be missing. For bitmaps 
that are mostly black and white, or 
mostly any two highly contrasting 
colors, most or all of the bitmap may 
appear in the client area at this 
stage. Clearly, the effect works best 
for bitmaps that are rich in a variety 
of colors. 

The key step occurs in the second 
for loop. The system palette entries 
for the bitmap are filled in one at a 
time with the true colors of the bit¬ 
map. I use a delay in the for loop, 
since otherwise the fade is blindingly 
fast. 

Each iteration of the loop replaces 
one entry in the system palette with 
the true color of the bitmap, for 
which I had previously substituted 
the color white. The bitmap appears 
to fade into the client area with each 
iteration of the loop as more and 
more color is added. When the effect 
is complete, I restore the system col¬ 
ors, clean up the resources I used, 
and return. 

Conclusion 

The block effect discussed here 
generates 2 77 - 7 coordinate values, 


Listing 2 continued 


I* animate palette one color at a time */ 
for (k=l; k<(int)w_colors-l;k++) { 

AnimatePalette (h_fadepal, k, 1, &p_pal->palPalEntry[k]); 
while (GetTickCountO < nextTime); 

/* compute wait interval - this formula shrinks the wait interval from 
200ms for 16 color images to 5ms for 256 color images */ 
nextTime += 213L - ((LONG)w_colors*(195L))/240L; 


/* release use of system palette */ 

UsePalette (h_memDC, FALSE); 

/* restore things to the way they were */ 
UnrealizeObject (h_pal); 
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Listing 2 continued 


SelectPalette thOC. h_pal. FALSE): 

SelectPalette (hjnemDC, hjal, FALSE); 

RealizePalette (hOC): 

RealizePalette (hjnemDC); 

/* clean up resources */ 
free (p_fadepal): 

DeleteObject (h_fadepa1): 

/* prevent paint update of window which causes flicker */ 
ValidateRect (hwndMain, NULL); 

return 8; 

} /* end function (bmpFade) */ 

/* End of File */ 
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which is probably more than most 
applications require. Changing the 
number of values generated by the 
pseudo-noise generator is a matter of 
changing the bit positions that are 
added modulo two to form the fill 
bit. The bit positions, called tap bits, 
for different length generators can be 
found in books on signal processing. 
I did not discuss the case when the 
width and height of the bitmap are 
not multiples of the block size, al¬ 
though this situation is relatively 
straightforward to deal with. 

For the fade effect, I assume that 
the palette table of the bitmap is ar¬ 
ranged in the configuration of a Win¬ 
dows Identity Palette (described in 
the Windows SDK Programmer's Refer¬ 
ence, Volume 7: Overview, Chapter 23). 
The effect will not work properly un¬ 
less the bitmap has an Identity Pal¬ 
ette. One reason is that the Identity 
Palette tries to arrange things so that 
the first and last palette entries for 
the bitmap have maximal contrast. It 
is simple enough to create an Iden¬ 
tity Palette: simply load the bitmap 
into Windows Paintbrush and save it 
again. Paintbrush always saves bit¬ 
maps with an Identity Palette. An¬ 
other requirement for this effect is 
that the video driver support palette 
manipulation. Palette manipulation is 
usually only supported by drivers 
that support more than 16 simultane¬ 
ous colors. The following code frag¬ 
ment checks for palette manipulation 
support from the video driver. 

/* make sure the driver supports 
palette animation */ 
if (!(RC_PALETTE & GetDeviceCaps 
(hDC, RASTERCAPS))) { 

MessageBox (NULL, "Palette 
Animation not Supported".MB_0K); 
return - 1; 

} /* end if (palette animation 
not supported) */ 


Algorithm References 

Black, Uyless. X.25 and Related Proto¬ 
cols. IEEE Computer Society Press. 
P. 61. 

Stallings, William. Data and Computer 
Communications. 4 ed. MacMillan 
Publishing. P. 147. □ 
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Listing 1 gray.c 

/************************************************** 

/************************************************** 

* Title: Graying Rectangular Regions in Windows 

* Functions 

* 

**************************************************j 

* This set of functions implements the "graying" 

/* Initializes the grayBrush */ 

* of rectangular regions in Windows. "Graying" is 

void graylnitiHINSTANCE inst) 

* accomplished by overlaying the region with a 

{ 

* checkerboard grid of dots. Every other dot’s 

grayBrush=CreatePatternBrush(LoadBitmap(inst."grayBmp") ) ; 

* color is the same as the device context’s current 

* background color. 

} 

* 

/* Deletes the grayBrush */ 

* Copyright (0 1993, Cain International Corporation. 

void grayExitiHINSTANCE inst) 

* All rights reserved. 

{ 

* 

if(grayBrush) 

* Author: Gregory C. Peters 

Irk************************************************/ 

//include <windows.h> 

{ DeleteObject(grayBrush); 
grayBrush = NULL; 

} 

} 

/************************************************** 

* Defines and Data 

**************************************************/ 

/* Grays the specified rectangular region */ 
void grayRecttHDC hdc, LPRECT r) 

{ 

ifthdc && r && grayBrush) 

/* these macros assume r is pointer */ 

#define RWIDTH(r) «r)->r1ght - (r)->left) 

{ HBRUSH oldBrush = SelectOb j ect ( hdc, grayBrush); 

#define RHEIGHT(r) (( r ) ->bottom - (r)->top ) 

PatBlt(hdc.r->left,r->top. RWIDTH(r).RHEIGHTtr),GRAYCODE); 

SelectOb j ect ( hdc. oldBrush); 

/* PatBlt code to do a bitwise OR between brush 

} 

* and the destination bitmap. 

*/ 

^define GRAYCODE 0xFA0089 

} 

/* End of File */ 

/* contains the checkerboard brush */ 
static HBRUSH grayBrush = NULL; 
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The fastest way to render the checkerboard pattern 
throughout the rectangular region is to PatBltO a brush 
into the region's device context. To make this work prop¬ 
erly, first create an 8x8 monochrome bitmap (brushes use 
only the first 8x8 bits) with a suitable pattern, for example: 

10101010 

01010101 


Next, load the bitmap and turn it into a brush using the 
LoadBitmapO and CreatePatternBrushO functions. Finally, se¬ 
lect the brush into the device context and PatBltO the 
brush into the destination bitmap with a bitwise OR raster 
code. The bitwise OR sets every pixel in the destination 
bitmap that corresponds to a 1 in the brush to the device 



Listing 3 testgray.c 


I* . 

TestGray.c -- Program to test the graying 
functions in gray.c. All it does is display 
a modeless dialog box with sample controls that 
are shown in normal states, disabled states, 
and "grayed" states. 

The modeless dialog box is used in lieu of a 
standard main window in order to minimize the 
code associated with the test program. 

This test program is modelled after Petzold's 
Hexcalc program in "Programming Windows". 

(c) Gregory C. Peters. 1994 
All Rights Reserved 

.*/ 

^include <window$.h> 

^include "resource.h" 

#include "gray.h" 

// window function for the modeless dialog, 
long CALLBACK grayProcCHWND hWnd, UINT message, WPARAM wParam, 
LPARAM 1 Pa ram); 

int PASCAL WinMainlHANDLE hlnst, HANDLE hPrevInst, LPSTR cmdLine, 
int nCmdShow) 

{ 

HWND hWnd; // handle to the modeless dialog 

WNDCLASS wc; // used to register the GrayTest class 

MSG msg; 
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Listing 3 continued 


long CALLBACK grayProc(HWND hWnd, UINT message, WPARAM wParam, 

if(lhPrevInst) 

LPARAM 1 Pa ram) 

{ // set up the window class structure 

{ 

wc.style = CS_HREDRAW 1 CS_VREDRAW; 

switch(message) 

wc.lpfnWndProc = grayProc; 

{ 

wc.cbClsExtra = 0; 

// Each control that has an id of IDGRAY WHITE is "grayed" 

wc.cbWndExtra = DLGWINDOWEXTRA: 

// with a pattern of white dots. Each control that has an 

wc.hlnstance = hlnst: 

// id of IDGRAY GRAY is "grayed" with a patten of gray dots. 

wc.hlcon = LoadlcontNULL, IDI APPLICATION); 

II 

wc.hCursor = LoadCursor ( NULL, IDC_ARR0W): 

II To minimize the associated code, the graying is done by 

wc.hbrBackground = C0L0R_WIND0W + 1; 

// drawing into a DISPLAY device context directly over the 

wc.lpszMenuName = NULL; 

// relevant controls. (Otherwise, would have to subclass 

wc.lpszClassName = "GrayTest"; 

// the controls themselves to modify how they are painted. 


case WM PAINT: 

RegisterClass(&wc ) ; 

{ HDC hdc, hdcDisplay; 

) 

PAINTSTRUCT ps; 


HWND child; 

graylnit(hlnst); // initialize the graying functions 

RECT rect; 

// create and show the modeless dialog 

hdc = BeginPaintthWnd, &ps); 

hWnd = CreateDialog(hInst, "GrayTest", 0, NULL); 

hdcDisplay = CreateDCC'DISPLAY”, NULL, NULL, NULL); 

ShowWindow(hWnd. SWJHOW); 



for(child = GetTopWindow(hWnd ) ; child; child = 

// do nothing message loop 

GetNextWindowtchi1d, GW HWNDNEXT) ) 

while(GetMessage(&msg, NULL, 0, 0)) 

{ i f (GetWindowWord(chi1d, GWW ID) == IDGRAY WHITE) 

{ TranslateMessageUmsg); 

{ // make sure the control is drawn first. 

DispatchMessage(Smsg); 

InvalidateRect(chi 1 d, NULL, FALSE); 

} 

UpdateWindowtchi Id); 

grayExit(hlnst); // clean up in the graying functions 

// Then gray the control with the "white" color 

return(msg.wParam); 


} 

SetBkColor ( hdcDi splay, GetSysColor ( C0L0R_WINDOW) ) ; 


GetWindowRect(chi1d. &rect); 

// grayProc window function 

grayRect(hdcDisplay, &rect); 


C and C++ DOCUMENTATION 


C-METRIC V (S59) COMPLEXITY / QUALITY 

• Calculates cyclomatic path complexity for functions and 


"cyctomatic path complexity 1 

■ Counts lines with comments, code, and 'C' statements 


system 


filel 

main 

file2 

—sub2 

file2 

—sub3 

file2 

1—sub4 

filel 

— main {recursv} 


— Ibryl, Ibry2 


C-CALL! m ($69) FUNCTION HIERARCHY 


Tree-Diagram showing function hierarchy 

• Table-Of-Contents of functions versus files 

• Summary and detailed cross-reference of functions 


C-CMT ($69) FUNCTION COMMENT 



r ff. 

sub2 USERS: main 

CALLS: sub3 sub4 
PARAM: argl arg2 
LOCAL: varl 
GLOBL: var2 var3 


Generates and inserts function comment blocks 

• Can be re-run to update the comment blocks 

• Retains any user-generated comments 

C-L1ST 1$69) LISTS OR REFORMATS^ 

• Action-Diagrams show logic/control flow 

• Optional line numbers, page numbers, and titles 

• Reformats source to various standardized formats 

C-REF™($59) CROSS-REFERENCES IDENTIFIERS 


■ Local/parameter/global/define summary or cross-reference 
• Produces class-hierarchy tree-diagram for C++ classes 

SPECIAL: ($199) C-D(Xr DOS Package ($325 Value) 


• All 5 programs fully integrated as 1 overall C-DOC program 

• Processes multiple directories/files up to 15,000 total lines 

• Unconditional 30-day money-back guarantee of satisfaction 

NEW: C-DOC M ProfessionaI ($299): DOS, OS/2, Windows 

• Processes 150,000 lines, 3-ring binder/case, 2-pass deferred reports 


!! NEW 5.0 !! Point-and-click G.U.I. operation !! 


SOFTWARE BLACKSMITHS INC 

6064 St Ives Way, Mississauga 
ONT Canada L5N-4M1 


Voice/Fax: I4161-X5X-4466 

Demo/BBS: (416)-858-1916 
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File Edit Bookmark Help 



'The right set of well implemented features...Good Support. 

Highly recommended" - Visual Basic Programmer's Journal, Jan-Feb '94 

HelpBreeze turns Word for Windows™ (version 6.0 or 2.0) 
into an integrated, point and click environment for creating, 
editing and testing cutting-edge Windows help systems. 


Feature Comparison 

Tool palette provides easy access to a 
complete set of visual authoring tools 

Automatically converts Word documents to 
Windows help files 

Automatically converts help files to 
printed documents 

Topic Wizard automatically creates and 
formats any number of help topics 

Built-in support for adding animation 
and slide shows to help files 

List Price 



YES 

YES 

NO 

YES 

YES 

YES 

YES 

YES 

YES 

YES 

NO 

NO 

YES 

NO 

NO 

$279 

$495 

$295 


| • s!i;i!.;i;i:i; !lji;i; i,, i 1 ' -n;ilif 


Only $279. Call Now and discover why industry leaders 
including AT&T, Digital Equipment and Hewlett-Packard 
are already using HelpBreeze! 

SolutiOmeM Tel: (408) 736-1431 

Fax: (408)736-4013 


999 Evelyn Terrace West, Suite 86 
Sunnyvale, CA 94086 

HelpBreeze is 


Unconditional 30-day money back guarantee! 
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context's current background color 
(as set by the SetBkColorO function). 
Every pixel in the destination bitmap 
that corresponds to a 0 in the brush 
remains unchanged. The PatBltO ras¬ 
ter op code for a bitwise OR between 
the brush and destination bitmap is 
0xFA0089 (Windows does not #define 
it). 

Listings 1 through 7 show an im¬ 
plementation of this technique for 
graying any rectangular region in 
Windows. The graying functions 
themselves are shown in gray, c (List¬ 
ing 1), while testgray.c (Listing 3) pro¬ 
vides a short application that demon¬ 
strates their effect on a variety of 
controls. 

The file gray.bmp, the checkerboard 
pattern bitmap, is included in the 
monthly code distribution. See the Online 
Source Code box in the table of contents 
for availability information. -Iz 


Listing 4 

gray.rc 

#include "resource.h” 

#include "windows.h" 

GRAYBMP 

BITMAP MOVEABLE PURE "GRAY.BMP" 

GRAYTEST DIALOG DISCARDABLE 20, 20, 263, 174 

STYLE WS VISIBLE 

WS CAPTION 1 WS SYSMENU 

CAPTION "Test Graying Functions" 

CLASS "GrayTest" 


FONT 8, "MS Sans Serif” 

BEGIN 


DEFPUSHBUTTON 

"button".IDNORMAL.il,26,60,14 

DEFPUSHBUTTON 

"button".IDGRAY WHITE,134,26,50,14 

DEFPUSHBUTTON 

"button".IDGRAY GRAY,203,26,50,14 

LTEXT 

"Normal",IDC STATIC,21,7,30,7 

LTEXT 

"grayed - gray background".IDC STATIC,205,2,48,20 

LTEXT 

"disabled".IDC STATIC,83,5.39.11 

LTEXT 

"sample text",IDNORMAL.il,54,41,10 

LTEXT 

"sample text”,IDGRAY WHITE,134,54,41,10 

COMBOBOX 

IDNORMAL.il,77,48,14.CBS DROPDOWN | CBS SORT I 


WS VSCROLL I WS TABSTOP 

COMBOBOX 

IDGRAY WHITE.134,77,48,30,CBS DROPDOWN I CBS SORT I 


WS VSCROLL | WS TABSTOP 

CONTROL 

"Radiol",IDNORMAL,"Button",BS AUTORADIOBUTTON,11,102,34, 

10 

CONTROL 

"Radiol",IDGRAY WHITE,"Button".BS AUTORADIOBUTTON,134, 

102,34,10 

CONTROL 

"Checkl",IDNORMAL,"Button",BS AUTOCHECKBOX I WS TABSTOP, 

11,125,34,10 

CONTROL 

"Checkl",IDGRAY WHITE,"Button”,BS AUTOCHECKBOX I 

WS TABSTOP.134,125,34,10 

SCROLLBAR 

IDNORMAL,11,148,40,11 

SCROLLBAR 

IDGRAY WHITE,134,148,40,11 



A Trick for Centering Text in Dialog Boxes 


Scott Courley 
Watertown, MA 
CIS 72311,613 
scott@metasoft.com 


When I create dialog boxes using the dialog editor that 
comes with the Microsoft Windows SDK, I often want to 
center some text within the width of the dialog box. 

The obvious way to do this is to create a text control 
large enough to hold the text, set the control's styles to 
include the SS_CENTER style, and then center the control 
horizontally within the dialog. 

But this last step takes a bit of work. Although the dia¬ 
log editor has a display area that indicates the size and 
position of a dialog control, you still have to do a little 
math on these numbers to figure out where to position 
the control. 

For example, in the BEFORE dialog box shown in Figure 
1 , you take the width of the dialog box, subtract the size 
of the control, and divide by 2 to get the horizontal posi¬ 
tion of the control within the dialog (132 - 54 = 78; 78 / 
2 = 39). 

Even worse, however, if you ever change the width of 
the dialog, or increase the length of the text string enough 
to require increasing the control's width, you have to re¬ 
calculate and reposition the control. 


Listing 3 continued 


} 

else if(GetWindowWordtchiId, GWWJD) == IDGRAY_GRAY) 

{ // make sure the control is drawn first, 

InvalidateRecttchi1d, NULL, FALSE): 
UpdateWindow(child); 

// Then gray the control with the "gray" color 

SetBkColorlhdcDisplay, GetSysColor(COLORJTNFACE)); 
GetWindowRectichiId, Srect); 
grayRectChdcDisplay, &rect); 

} 

} 

DeleteDC(hdcDisplay): 

EndPaintlhWnd, &ps); 
break; 

} 

// make sure that closing the dialog exits the application 
case WHJESTROY: 

PostQuitMessage(0); 

return(0); 

} 

return(DefWindowProc(hWnd, message, wParam, 1Param)); 

} 

/* End of File */ 
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Listing 4 

continued 

SCROLLBAR 

IDGRAY GRAY,203,148,40,11 

LTEXT 

"grayed - white background”,IDC STATIC,138,2,48,20 

DEFPUSHBUTTON 

"button",IDNORMAL,72,26,50,14,WS DISABLED 

LTEXT 

"sample text",IDNORMAL,72,54,41,10,WS DISABLED 

C0MB0B0X 

IDNORMAL,72.77,48,30,CBS DROPDOWN I CBS SORT I 

WS DISABLED I WS VSCROLL i WS TABSTOP 

CONTROL 

"Radiol",IDNORMAL,"Button",BS AUTORADIOBUTTON 1 

WS DISABLED,72,102,34,10 

CONTROL 

"Checkl",IDNORMAL,"Button",BS AUTOCHECKBOX 1 

WS DISABLED I WS TABSTOP,72,125,34,10 

SCROLLBAR 

END 

IDNORMAL,72,148,40,11,WS DISABLED 


Instead of going to all this trouble, 
I use a technique that makes the 
hardest part of the process the easi¬ 
est part. I still create a text control 
with the SS_CENTER style, but I make 
the width of the control the same as 
the width of the dialog box (see Fig¬ 
ure 2), which causes the text to be 
automatically centered on the dialog. 
No horizontal positioning is neces¬ 
sary, or even possible, so you can't 
make a mistake in the positioning, or 
accidentally nudge it off-center later. 


Listing 5 resource.h 


//{{NO_DEPENDENCIES}} 

// App Studio generated include file. 

// Used by GRAY.RC 
// 


//define IDC STATIC 

999 

//define IDNORMAL 

1001 

//define IDGRAY WHITE 

1002 

//define IDGRAY_GRAY 

// Next default values for new objects 
// 

t ifdef APSTUDIO INVOKED 
//ifndef APSTUDIO_READONLY_SYMBOLS 

1003 

//define APS NEXT RESOURCE VALUE 

101 

//define APS NEXT COMMAND VALUE 

101 

//define APS NEXT CONTROL VALUE 

1014 

//define _APS_NEXT_SYMED_VALUE 
//endi f 
//endi f 

/* End of File */ 

101 


Listing 6 gray.def 


; Gray.def module definition file 

NAME 

GrayTest 

DESCRIPTION 

'Test Gray program. (C) Gregory C. Peters, 1994’ 

EXETYPE 

WINDOWS 

STUB 

•WINSTUB.EXE’ 

CODE 

PRELOAD MOVEABLE DISCARDABLE 

DATA 

PRELOAD MOVEABLE MULTIPLE 

HEAPSIZE 

1024 

STACKSIZE 

8192 

EXPORTS 

grayProc 


Listing 7 gray.mak 


//. 

# GRAY.MAK: Make file for testgray program 
//. 

WINCC = bcc -c -w-par -P -W -2 

WINLINK = tlink /x /c /n /Tw /L$(LIB) c0ws 

WINLIB = import mathws cws 

WINRC = rc -r -ie:\bc4\include 


testgray.exe : testgray.obj gray.obj gray.def gray.res 
$(WINLINK) testgray gray, gray, NUL, $(WINLIB), gray 
rc -t gray.res 

gray.obj : gray.c gray.h 
J(WINCC) gray.c 

testgray.obj : testgray.c gray.h 
$(WINCC) testgray.c 

gray.res : gray.rc gray.h gray.bmp 
$(WINRC) gray.rc 


Listing 8 dualexe.pas 


} 
} 
) 
) 
) 
) 
} 

Type 

{Old-Style MSDOS header) 

ExeHeader = Record 
sig :Word; 
lpsizeiWord; 
pgcnt :word; 
ri terns:Word; 
hdrsize:Word: 
minalloc.Maxalloc:Word: 
datal :Longint; 
chksum :Word; 

data2 :Array[S14..$17] of byte: 
rtofs :Word; 
ovrnum :word; 

data3 :Array[$lC..$3b] of byte: 

winhdr :longint: 

end: 

{New style Windows header) 

NewHeader = Record 


Program DualExe; 

{ Windows/DOS application combiner. 

{ This program will combine a Windows and a DOS application together 
{ to produce a "dual-mode" executable. The algorithm used here involves 
{ reading header and image data from two existing applications and 
{ creating a new application by transfering the program image data from 
{ from each application and then merging the headers. 
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Furthermore, you can change the text string to any¬ 
thing that will fit within the dialog's width, and it will auto¬ 
matically remain centered. If you change the width of the 
dialog box, just change the width of the centered text con¬ 
trols as well, and they will stay centered. 

One minor additional issue: if other controls overlap 
your wide text controls - as, for example, an icon on an 
about box - just make sure they are listed in the dialog 
template after the static text controls, so that the white 
area of the text controls won't obscure them. Also, make 
sure they don't obscure any underlying text. 

A Utility to Construct Windows/DOS 
"Dual-Mode" Applications 


Paul Bixel 
Salem, VA 
CIS: 71055,423 
Internet: Bixei_PS@salem.ge.com 

An examination of the Windows executable file for¬ 
mats shows that it actually contains two complete pro¬ 
grams. Usually, a DOS 'stub' proceeds a more substantial 
Windows load image. The stub is in fact an entire DOS 
program, and in fact the term "stub' is a bit misleading, 
since the .EXE format places virtually no restrictions on the 
contents of the 'stub'. Instead, it seems that the linkers 
commonly used to create Windows applications place limi¬ 



Figure 1 Dialog template with centered dialog 
control 


BEFORE DIALOG 12, 18, 132, 90 

STYLE DS_MODALFRAME I WSJOPUP I WSJISIBLE I WSJAPTION I WSJYSMENU 
CAPTION "Dialog Title” 

FONT 8, "MS Sans Serif" 

BEGIN 

CTEXT "Centered Text", 104, 39, 14, 54, 8 

END 


Figure 2 

Dialog template with “wide” text controls 

AFTER DIALOG 12, 

18, 132, 90 

STYLE DS MODALFRAME I WS POPUP 1 WS VISIBLE I WS CAPTION 1 WS_SYSMENU 

CAPTION "Dialog Title" 

FONT 8, "MS Sans Serif" 

BEGIN 


CTEXT 

"More Centered Text", 101, 0, 26, 132, 8 

CTEXT 

"Still More Centered Text”, 102, 0, 38, 132, 8 

CTEXT 

"Last Bit Of Centered Text", 103, 0, 50, 132, 8 

CTEXT 

"Centered Text”, 104, 0, 14, 132, 8 

ICON 

"AfterTest", 105, 5, 5, 32, 32 

END 



tations on the 'stub' they will accept to create an ex¬ 
ecutable. Some limit the size of the executable, while oth¬ 
ers include only the load image and not any appended 
overlays. In the Microsoft Windows philosophy, the stub 
was intended only to print out the now famous 



3 CD-ROM 

Wainut Creek CDROM 


Software 
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• C Users' Group Library R01 $49.95 

Volumes 100 to 364. Source code for editors, disassemblers, compilers, interpreters, communications, games, tutorials, math libraries. Most 
code for MSDOS, much for UNIX and other systems. Disk includes the first three text editions of the CUG Directory: indexing and describing 
every file and reviewing major packages. 


• Libris Britannica R02 $69.95 

Public domain and shareware from PDSL, Sussex, for DOS: extensive sections on electronics, engineering, mathematics, medicine, ham 
radio, including the entire C Users' Croup UK archive. 


• Source Code R03 $39.95 

The Usenet archives, Simtel20 Unix-C archives, and a large collection of MSDOS source code. Simtel20 Unix-C are mostly complete working 
programs for archiving, benchmarks, databases, editors, file management, graphics, compilers and interpreters, printer utilities, communications, 
networking. MSDOS source is almost 2000 Zipped packages including Autocad utilities, editors, archivers and compression programs, 
emulators, compilers and interpreters; mostly C source code. 


• CICA Microsoft Windows R04 $24.95 

The entire CICA Windows Collection from Indiana University, hundreds of utilities, including shells, disk utilities, mouse and keyboard utilities, 
screen savers, backup/restore programs, performance monitors, diagnostics, data conversion programs, and games. 


• SIMTEL20 MSDOS R05 $24.95 

The entire Simtel20 MSDOS archive, 640 megabytes in 9000+ files. Many include source code, usually in C. Programming tools for APL, assembly, 
C, Pascal, Perl, Prolog, Smalltalk, etc. Communications utilities, BBS's, compression programs, shells, editors, graphics, menus, and games. 

• Garbo MSDOS/Mac R06 $24.95 

Contains the MSDOS and Mac archives from the University of Vaasa, Finland, almost all in English from Europe and America. MSDOS files are 
250 megabytes including programs for animation, archive utilities, BBS's programming tools, system utilities, business, science, education. 


To Order Call 913-841-1631 FAX 913-841-2624 
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Listing 8 continued 




sig :Word: 

End; 

ver Word; 


etofs Word; 

assign(fd,paramstr(U); 

etlen Word; 

assignffw.FileName): 

chksum:Longint; 

assign(fn,paramstr(3)); 

flags Word; 


datal :Array[50e..$lb] of byte; 

reset(fw.l); 

stent :word; 

reset(fd.l); 

data2 :Array[$le..$21] of byte; 

rewrite(fn.l): 

stoff :word; 


rtofs :word; 

blockreadffw,fwhdr,sizeof(fwhdr)); 

data3 :Array[$26..52b] of byte; 

blockreadlfd,fdhdr,sizeof(fdhdr)); 

nroff :Longint; 


epent Word; 

{Read the windows file New Header) 

asent Word; 

seekffw,fwhdr.winhdr); 

rsent Word; 

blockread(fw,nh,sizeof(nh)): 

osflg :Byte; 


exeflg:Byte; 

{New Old Style header most like DOS program’s) 

flofs Word; 

fnhdr := fdhdr; 

end: 



{Calculate the DOS Load Image size) 

{Segment table records) 

dimage := fdhdr.pgent*!ongint(512) + fdhdr.lpsize - 

SegTabEntry = Record 

fdhdr.hdrsize*longint(16)-1ongint(512); 

segoff:word; 


datal:Array[2.,7] of byte; 

fnhdr.rtofs ;= 548; {Switch to windows form) 

end: 

fnhdr.chksum := 0; {We’re to lazy to re-do checksums.) 

{Resource table group records) 

{Calculate Alignment Shift) 

ResGrpEntry = Record 

shent := nh.asent mod 9; 

RestypeWord; 

if shcnt=0 then shent := 9; 

Resent ; Word: 

alignment := 1 shl shent; 

data :Array[4..7] of byte 


end; 

Where will the new windows header be?) 
fnhdr.winhdr := 

{Resource table records) 

(((filesize(fd)+ 540 - fdhdr.rtofs + alignment -1) shr shent) shl shent); 

ResTabEntry = Record 


ResOfs Word; 

{Calculate the new header size in paragraphs) 

ResLen :Word; 

fnhdr.hdrsize := (540+fdhdr.ritems*4 + 15) div 16; 

data :Array[4..11] of byte 


end; 

{Calculate new file size parameters) 
fnhdr.lpsize := (fnhdr.hdrsize*16 + 

Var 

dimage) mod 512; 

filename;String; 


Setlcon boolean; 

fnhdr.pgent := (fnhdr.hdrsize*16 + 

dimage+511) div 512; 

fw. Windows application input file) 


fd, {DOS application input file) 

Write the Old-Style header to the new file) 

fn :File; {New file output handle) 

blockwrite(fn,fnhdr, $40); 

fwhdr, fdhdr, fnhdr:ExeHeader; {Old Style headers) 


nh:NewHeader; {New Style header for Windows App) 

{Write the DOS relocation table) 

resgrp:ResGrpEntry; 

seekffd,fdhdr.rtofs); 

resent:ResTabEntry; 

If fdhdr.ritems>0 then 
begin 

buffer:Array[l..1024*30] of byte; {Transfer buffer) 

blockread(fd,buffer,fdhdr.ritems*4 ) ; 

i:word; 

blockwrite(fn,buffer,fdhdr.ritems*4); 

achange:Integer; 

end; 

dimage:Longint; 


alignment:word; 

{Write up to the next paragraph] 

shcntWord; 

i := filepos(fn); 

stent:SegTabEntry; 

f111cha r( buffer, si zeof(buffer),char(0)); 

j :Longint; 

if i mod 16 <> 0 then 

blockwrite(fn,buffer,16-(i mod 16)); 

Begin 



{Transfer the entire DOS Image) 

If Paramcount<>3 then 

seek! fd .fdhdr.hdrsize*16) ; 

begin 

repeat 

Writeln('DUAL-MODE executable creator, vl/1/93’); 

blockread ( fd,buffer,sizeof ( buffer ) ,i ); 

Writeln('Usage: '); 

if (I>0) then blockwrite(fn,buffer,i ); 

WritelnC dualexe <dosapp> CWinApp I WinIcon> <NewAppName>'); 

until (10s izeof ( buffer )); 

exit; 


end; 

(Fill out the last page till the Windows Header) 
if fnhdr.winhdr-filepos(fn»0 then 

Setlcon := False; 

begin 

FileName := Paramstr(2); 

fillchartbuffer,sizeof(buffer),char(0)); 

I:=l; 

blockwrite(fn,buffer,fnhdr.winhdr-fi1epos(fn) ); 

while Length(Fi1eName)>i do 

end; 

begin 


FileName[i] := UpCase(Fi1eName[i ]); 

{Compute the adjustment for segment oriented offsets) 

Inc(i); 

if fnhdr.winhdr>=fwhdr.winhdr 

end; 

then achange := (fnhdr.winhdr - fwhdr.winhdr + alignment -1) shr shent 
else achange := - ((fwhdr.winhdr - fnhdr.winhdr + alignment -1) shr shent); 

If Pos(FileName,’.ICO’)>0 then 

Begin 

{Adjust the fast-load area if used) 

FileName := ’LAUNCH.EXE'; 

if (nh.exeflg and 8) > 0 then inclnh.flofs,achange); 

Setlcon := True; 


Page 60 — Windows/DOS Developer’s Journal 


May 1994 










“This program requires Microsoft Windows” 

message when someone attempted to run the program 
from the DOS command line. 

It is actually quite simple to overcome the limitations of 
program linkers and create full-blown 'dual-mode' applica¬ 
tions. Such applications contain a complete DOS program 
and Windows program within one file image. When a 
user runs the program from the DOS command line, the 
DOS program runs; when the user launches the same pro¬ 
gram from Windows, the Windows application executes. 
This can be handy if you are currently distributing and 
supporting both a Windows and DOS version of an appli¬ 
cation. With both applications in the same file, your users 
need not worry about which one to 


Listing 8 continued 


{Adjust the new header name table offset) 
nh.nroff := nh.nroff - fwhdr.winhdr + fnhdr.winhdr; 

{Blank the checksum) 
nh.chksum := 8; 

{Insert the entire windows application header and image) 

seek(fw.fwhdr.winhdr+sizeof(nh)); 

blockwrite(fn.nh.sizeofCnh)); 

repeat 

bl ockread(fw,buffer,sizeof(buffer),i); 
if (i>0) then blockwrite(fn,buffer,i); 
until (iOsizeof(buffer)); 


{Go Back and fix segment table offsets) 


run. 

The utility I describe is a simple 
application written in Pascal which 
takes as its input both a DOS and a 
Windows program. It then combines 
the two and creates a third ex¬ 
ecutable which contains both applica¬ 
tions. To accomplish this, it reads the 
executable file headers of both pro¬ 
grams and adjusts all the relative off¬ 
sets when creating the third applica¬ 
tion. The new program is actually a 
Windows executable which contains 
the DOS application as its 'stub.' 

Network administrators may find 
this utility handy since it lets you 
combine any two applications with¬ 
out access to object or source code 
from either one. You will have one 
less file on your file server and your 
users will not become confused in a 
mixed DOS/Windows environment. 

The command-line syntax for this 
utility is as follows: 

dualexe D0S_EXE WindowsJXE New_EXE 

To combine the DOS and Windows 
versions of WordPerfect, use the fol¬ 
lowing syntax: 

C:\> dualexe \wp\wp.exe \wp\wpwin.exe 
\wp\both.exe 

Use this utility along with the tech¬ 
nique described by Mark Nelson in 
the Tech Tips column of the Decem¬ 
ber 1993 issue of W/DDJ and you 
can add icons to any size DOS appli¬ 
cation. 

While I cannot guarantee that all 
DOS programs can be successfully com¬ 
bined with Windows applications with 
this utility, I have used it on several 



for C/C++ 

presents Bug # 606 


#include <stdio.h> 

char *default_file = "C:\TMP\TMP"; 

int main() 

{ 

FILE *f; 

f = fopen( default_file, "r" ); 
if( f ) return 0; 
else return 1; 

} 

. 


The programmer is certain that file TMP in directory TMP exists but this 
program acts as if it isn't there. What’s wrong? Call if you need a hint. 
Refer to Bug #606. 


PC-Iint for C/C++ will catch this and many 
other bugs. It will analyze a mixed suite of C 
and C++ modules to uncover bugs, glitches, 
quirks and inconsistencies. 

Numerous C++Warnings and Messages: 
Are your inherited destructors virtual? Are 
your constructor new's matched by your 
destructor delete's? Are your initializers 
in order? Are names inadvertently hiding 
other names? Are your C++ modules 
consistent with your C modules? Much, 
much, more. 

Plus Our Traditional C Warnings: 

Uninitialized variables, unaccessed variables, 
possibly uninitialized variables, strong type 
mismatches, indentation irregularities, loss of 
precision, strange uses of Booleans, 
signed/unsigned mismatches, suspicious 
expressions, unused macros, etc. etc. 


Full C++ Support - PC-lint for C/C++ 
is based on the ARM and is tracking the 
latest ANSI/ISO draft including exceptions 
and templates. It supports both Borland and 
Microsoft C/C++. 

Options Galore: A plethora of options for 
message suppression, message format, 
compiler dependencies, etc. All messages 
can be individually suppressed or enabled, 
both locally and globally. Numerous 
compilers/ libraries supported. Runs on 
MS-DOS (Optional built-in 386 DOS 
extender) and OS/2. 

PC-lint for C $139 
PC-lint for C/C++ $239 

PC-lint users: call for update pricing 
Unix and Mainframe programmers: 
call for pricing for FlexeLint. 


©imp©] S@ftw©T(© 

3207 Hogarth Lane, Collegeville. PA 19426 

CALL TODAY (610)584-4261 Or FAX (610)584-4266 

30 Day Money-back Guarantee. 

PA add 6% sales tax. PC-lint and FlexeLint are trademarks of Gimpel Software 
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Listing 8 continued 


seek(fn,fnhdr.winhdr+nh.stoff); 

repeat 

seek(fW.fwhdr.winhdr+fih.stoff); 

bloc kread(fn.res grp,sizeof(res grp)); 


blockread(fw,resgrp,sizeof(resgrp)); 

while nh.stcnt>0 do 


begin 

while (resgrp. restypeOB) and (resgrp.rescnt>0) do 

blockreadtfw,stent,sizeofCstent)); 

begin 

if (stent.segoffOB) then 1nc(stent.segoff,achange): 

blockreadt fw.resent,sizeof(resent)); 

blockwrite(fn,stent,sizeof(stent)); 

inc(resent.resofs.achange); 

dec(nh.stcnt); 

bl ockwrite( fn,resent.sizeof(resent)); 

end; 

declresgrp.resent); 


end; 

{Now Doctor up the resource tables offsets) 


seek(fw,fwhdr.winhdr+nh.rtofs); 

until (resgrp.restype=0); 

seek(fn.fnhdr.winhdr+nh.rtofs+2); 


blockread(fw,shcnt,2); 


alignment := 1 shl shcnt; 

{Done so close everyone up) 


close(fn); 

if fnhdr.winhdr>=fwhdr.winhdr 

close(fd); 

then achange := (fnhdr.winhdr - fwhdr.winhdr + alignment -1) shr shcnt 

close(fw); 

else achange := - ((fwhdr.winhdr - fnhdr.winhdr + alignment -1) shr shcnt); 



End. 


{ End of File } 


large commercial applications myself without problems. 
Try combining the DOS and Windows versions of your fa¬ 
vorite application. 

For more information on .EXE headers, I recommend The 
MS-DOS Encyclopedia and the Developer Network CD (now the 
Microsoft Development Library), both from Microsoft and on 
which I depended heavily when creating this utility. 


The source code for Dualexe is shown in Listing 8. This 
utility can be compiled with any version of Borland/Turbo 
Pascal (I use Borland Pascal v7.0t myself). 

dual .pas as supplied by Paul (and shown in Listing 8) re¬ 
quires each command line argument to be written out with a 
full pathname. The executable, dualexe.exe, is included with the 
monthly code distribution. See the Online Source Code box in 
the table of contents for availability information. -Iz □ 



Find 6 years of indepth real-world information in seconds. 
Unleash the full potential of your C User’s Journal and 
Windows/DOS Developer’s Journal library. 

• Detailed three-level subject index. 

• Each article, letter, and question and answer listed under 
numerous indexing terms. 

• All entries include the title, author, and references to other 
articles, journal issue, and page. 


Special Offer 


For Owners of the 1992 Index, 
buy the update for only $9.95! 
Order W63DU. 



Identify Source Code INDEXW1 to Order W63D Today! 

Call 913-841 -1631 FAX 913-841 -2624 

1601 West 23rd Street, Suite 200, Lawrence, Kansas 66046-2700 


□ Request 181 on Reader Service Card □ 
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Q When a listbox is initially created it will have some apparent length. How¬ 
ever, if I draw a border around this edge, I find that the listbox length 
changes at run time. This in itself is somewhat understandable, since it appears 
that the length of a listbox must always be an even increment of the font 
displayed within. However, if I subclass this listbox and then draw the border 
when the window receives its MM_PAINT message, I end up with two borders. 
One border is at the original edge of the box, the second is at the displayed 
edge of the listbox. It appears that listboxes get sent two MM_PAINT messages: 
how can I determine which one to process? At present I am making the deter¬ 
mination by assuming that the window will continue to get MM_PAINT messages 
until its length is in fact an even increment of its display font. 

Kent Bair 
CIS: 72570,444 

A Listbox sizing is one of the more arcane aspects of Windows. To give you 
a better understanding, let me explain what happens during a listbox size 
operation. When a listbox is first created, or when its size is changed under 
program control, Windows sends the listbox a MM_NCCALCSIZE message. This mes¬ 
sage allows a window to specify the desired size of its client area, within the 
confines of the entire window. Normally, the MM_NCCALCSIZE message will get 
passed along to DefMindowProcO, which will make some generic calculations of 
the correct client area size. If the listbox window has a border (has the MS_B0R- 
DER style), then DefMindowProcO will indent its client area by one border unit 
along each edge of the window. A border unit in the horizontal direction (the 
width of a vertical border) is the value returned by calling GetSystemMetricsO 
with the SM_CXBORDER constant ( SM_CYBORDER returns a vertical border unit). If a 
window has a scroll bar, DefMindowProcO subtracts the width of the scroll bar 
from the width of the whole window, further reducing the size of the client 
area. 

Paul Bonneau 



Send questions to Paul via Internet as 

paul@rdpub.com 

from CompuServe: 

>INTERNET: pau l @rdpub. com 
or in care of this magazine at: 

1601 W. 23rd St, Suite 200 
Lawrence, KS 66046-2700. 

Paul answers all electronic 
communications but is unable to 
respond personally to hard copy/disk 
messages. 


Paul was a developer of HyperChem, a molecular modeling system, and more recently, 
of Creative Writer, a word processor for children. He works for Microsoft Corporation as 
a Software Design Engineer. The opinions expressed in this column are Paul's alone 
and not those of Microsoft 






















Table 1 IParam bit fields for keyboard messages 

Field 

Bits 

Mask 

Description 

Repeat Count 

0 - 16 

OxOOOOffff 

Holding down a key causes it to 
auto-repeat. This is the auto-repeat 
count since the last message. 

Scan Code 

16-23 

OxOOffOOOO 

Hardware dependent key identifier. 

Extended key 

24 

0 x01000000 

Specifies if key is an extended key 
(function, extra controi/shift/enter, 
numpad, etc.) 

Unused 

25 - 26 

0x06000000 


Reserved 

27 - 28 

0x18000000 

Reserved for internal Windows use. 

Alt key 

29 

0 x20000000 

State of the Alt key, set if down. 

Previous 

30 

0x40000000 

Previous key state, set if down. 

Transition 

31 

0x80000000 

Key transition state, set if key is 
being released. 


After the WM_NCCALCSIZE message returns, Windows 
sends a WM_SIZE message to the listbox to inform it of its 
new size. If it was created without the LBS_NOINTEGRALHEIGHT 
style, the listbox will first obtain its outer window rectan¬ 
gle in screen coordinates. Then, using similar logic to De- 
fUindowProcO to account for borders and scroll bars, the 
listbox code calculates a new length for the listbox such 
that the client area will contain an integral number of list- 
box entries (which depends, as you pointed out, on the 


listbox's current font). The listbox will 
then call SetWindowPosO to adjust its 
own window height. 

This starts the whole process all 
over again: Windows will again send 
a UM_NCCALCSIZE message, DefUindou- 
ProcO will adjust the client area, and 
the listbox will receive another 
UM_SIZE message. A point to note 
here is that since the listbox called 
Setk/indowPosO while processing a 
klM_SIZE message, the second set of 
messages will be handled by nested 
calls to the listbox window proce¬ 
dure. This reentrancy would quickly 
blow your stack were it not for a 
check at the start of the listbox resiz¬ 
ing code. The listbox resizing code 
skips the call to SetUindowPosO if it 
determines that the client area is al¬ 
ready an integral number of listbox 
entries high. If you create a listbox 
with the LBSJOINTEGRALHEIGHT style, 
the listbox sizing code is not exe¬ 
cuted when the listbox receives a UM_SIZE message. 

Since the border is part of the non-client area, it is 
painted in response to the UM_NCPAINT message, not the 
UM_PAINT message, which explains your problem with two 
borders. I think the problem stems from the fact that the 
listbox is drawing its border for the recalculated size, while 
your code in the UM_PAINT message is using the original 
size. If you want to draw your own border, you should do 


Listing 1 keymap.h — Declarations for keyboard 
remapper DLL 


Listing 2 keymap.c — Definitions for keyboard 
remapper DLL 

! ★*★*★★★★★★*★*★★★★★★★★★*★***★*★★************★********* j 


/***************************************************** j 

/* keymap.h */ 


/* keymap.c */ 

/* -- Interface to keyboard remapper DLL. */ 


/* -- DLL remaps keyboard keys. */ 

! ★★★★*★★*****★★★*★***★★******★★***★★**★*******★★****** j 


/* -- To compile: cc -wd -DSTRICT keymap.c */ 

typedef struct 


/*****************************************************/ 

{ 


(/include <windows.h> 

UINT vkc; /* Virtual key code. */ 


(/include "keymap.h" 

UINT wExt; /* Extension/scan bits. */ 


} KEY, far *LPKEY; /* A KEY specifier. */ 


typedef struct KRN /* Key code Remap Node. */ 

{ 

struct KRN *pkrnNext; 

typedef struct 


{ 


KRI kri; 

KEY keyFrom; /* Source key. */ 


} KRN; 

KEY keyTo; /* Destination key. */ 



} KRI, FAR *LPKRI: /* Key code Remap Info. */ 


HINSTANCE hins : /* This DLL’s instance. */ 

HHOOK hhok; /* Message hook handle. */ 

BOOL WINAPI export FSetKri ( LPKRI Ipkri); 


KRN *pkrnHead: /* Map list head. */ 

BOOL WINAPI ^export FGetKri ( LPKRI Ipkri); 


BOOL WINAPI _export FNextKri(LPKRI Ipkri, LPKEY lpkey); 


int CALLBACK LibMain(HINSTANCE hinsThis, WORD wDS, 

BOOL WINAPI _export FRemoveKey(LPKEY lpkey); 


WORD cbHeap, LPSTR lpsz); 

BOOL WINAPI _export FMapEnable(BOOL fEnable); 


LRESULT CALLBACK export LwMsgHooktint code, 

void WINAPI _export ResetMap(void); 


WPARAM wParam, LPMSG lpmsg); 
int CALLBACK export WEP(int wExitCode); 

/* Set a key from an IParam. */ 


KRN **PpkrnFind(LPKEY lpkey); 

#define GetKeyMsgtkey, wParam, IParam) \ 


BYTE BSetVkcdlINT vkc, BYTE bSet); 

((key).vkc = (UINT)wParam, \ 



(key).wExt = (UINT)(((1 Pa ram) & Ox01ff0000) » 16)) 


int CALLBACK LibMain(HINSTANCE hinsThis, WORD wDS, 

/* End of File */ 


WORD cbHeap, LPSTR lpsz) 


Page 64 — Windows/DOS Developer’s Journal 


May 1994 























INFORMATION 


Window^/DOS 

□ DEVELOPER'S JOURNAL 





Here’s how: 

To receive free product information 
from the companies listed on this 
page, simply follow these steps: 

1) Call 1 -800-234-0114 from any 
phone. 

2) Follow the voice prompts; 
be sure to have the product 
document number and your 
FAX number handy. 

3) That’s it! The information 
you’ve requested is FAXed 
to you immediately. 

It’s simple, easy, and FREE. 

Don’t miss the additional 
information available about 
Windows/DOS Developer’s Journal. 
You can receive information about 
books, back issues, code availabil¬ 
ity, and much more. 

Thank you for using 
Windows/DOS Developer’s 
Journal Instantlnfo Response 
Service! 


Instantlnfo” 

Response 

Service 


Advertiser Page Document 


Anchor Software. 

. . 85. 

. 1069 

AutoData Systems. 

. . 52. 

. 1061 

Blue Lagoon Software. 

. . 85. 

. 1078 

Burton Systems Software. 

. . 39. 

. 1064 

Catenary Systems. 

. . 50. 

. 1052 

DART Communications. 

. . 84. 

. 1079 

Distinct Corporation. 

. . 47. 

. 1076 

Information Architects. 

. . 86. 

. 1054 

Inner Media. 

. . 87. 

. 1074 

Intelec System. 

. . 87. 

. 1070 

Octagon Trade Group, Inc. 

. . 85. 

. 1055 

Pearl Software. 

. . 28. 

. 1080 

Phase3 Software. 

. . . 5. 

. 1057 

Sangoma Technologies. 

. . 85. 

. 1071 

Software Blacksmiths. 

. . 56. 

. 1058 

Subtle Software, Inc. 

. . 87. 

. 1081 

Wintertree Software. 

. . 85. 

. 1077 

Magazine Services 


Document 

WDDJ subscription information. 


. 1120 

Code disk subscriptions. 


. 1121 

Code availability. 


. 1122 

Back issues. 


. 1123 

WDDJ Author Guidelines. 


. 1124 

Online Index to WDDJ. 


. 1125 

C Users’ Group Software Library. 


. 1126 

C Users Journal subscription information . . 


. 1127 

Mailing lists. 


. 1128 

Book Information 


Document 


C++ Programming Guidelines (Plum & Saks). 1129 

C Programming Guidelines, 2nd Ed. (Plum). 1130 

Illustrated C (Zolman). 1131 

MS-DOS System Programming, 2nd Ed. (Ward). 1132 

pC/OS The Real Time Kernel (Labrosse). 1133 

Windows Custom Controls (Smith & Ward). 1134 

Object Oriented Software Engineering (Halladay/Wiebel) 1135 

The Standard C Library (Plauger). 1136 

Windows/DOS Developer’s Bookshelf Catalog. 1138 


Free Product Information — 24 hours a day! 

1 - 800 - 234-0114 


May 1994 


Windows/DOS Developer’s Journal — Page 65 





































































Listing 2 continued 


i 

/* -- Find the key mapping. */ 

/* -- Initialize the key map array. */ 

/* -- lpkey : Source key for mapping to find. */ 

1 ************ *****************************************j 
{ 

hins = hinsThis; 
return FMapEnable(TRUE); 

/*****************************************************y 

{ 

KRN **ppkrn; 

} 

for (ppkrn = ApkrnHead; NULL != *ppkrn; 
ppkrn = &(*ppkrn)->pkrnNext) 

BOOL WINAPI _export FMapEnable(BOOL fEnable) 

if ((*ppkrn)->kri.keyFrom.vkc == lpkey->vkc && 

y**★★*******★**★★★*★*★★★★*★**★★★★*****★*************★* j 

(*ppkrn)->kri.keyFrom.wExt == lpkey->wExt) 

1* -- Enable (or disable) all keyboard mappings. */ 

return ppkrn; 

/* -- Return the new state. */ 

return NULL; 

j★★*★★★*★★★★★*★*★*★★★★*★***★**★*★★★***★****★★★★★★*★**★i 
{ 

if (fEnable && NULL == hhok) 

} 

BYTE BSetVkc(UINT vkc, BYTE bSet) 

hhok = SetWindowsHookEx(WH GETMESSAGE, 

/*****************************************************/ 

( H00KPR0C ) LwMsgHook, hins, NULL); 

/* -- Set the given key to the given state. */ 

else if ( IfEnable && NULL != hhok) 

/* -- Return the previous state. */ 

{ 

!★★★*★★★★★****★*****★★★*★★★*****★*★★★*★★★★*★★**★★★★★★★j 

UnhookWindowsHookEx(hhok); 

{ 

hhok = NULL; 

} 

return NULL != hhok; 

BYTE b, rgb[256]; 

GetKeyboardState(rgb); 

} 

b = rgb[vkc]; 
rgb[vkc] = bSet; 

int CALLBACK _export WEP(int wExitCode) 

SetKeyboardState(rgb); 

/★**★★***★**★★★★★**★*★★★*★*******★★*****************★* j 

return b; 

1* -- Remove the message hook. */ 

} 

{ 

BOOL WINAPI _export FSetKri ( LPKRI lpkri) 

FMapEnable(FALSE); 

/*****************************************************/ 

return TRUE; 

/* -- Add the given key mapping, alloc may fail. */ 

} 

/* -- lpkri : Mapping to add. */ 

J*****************************************************/ 

LRESULT CALLBACK _export LwMsgHook(int code, 

{ 

WPARAM wParam, LPMSG Ipmsg) 

/*****************************************************/ 

KRN **ppkrn, *pkrn; 

/* -- GetMessageO hook maps keyboard messages. */ 

if (VK MENU == lpkri->keyFrom.vkc II 

j *★*★*★★★**★*★**★*★★*★*****★★*★*★★*★★**★★***★***★***★* j 

VK MENU == lpkri->keyTo.vkc) 

{ 

KRN **ppkrn; 

return FALSE; 

KEY key; 

if (NULL != (ppkrn = PpkrnFind(&lpkri->keyFrom) )) 
pkrn = ‘ppkrn; /* Already mapped? */ 

if (code < 0) 

else 

goto LCal1 Next; /* SDK says leave alone. */ 

{ 

if (lpmsg->message != KM KEYDOWN M 

pkrn = (KRN *)LocalA11oc(LPTR, sizeof(KRN)); 

lpmsg->message 1= WM KEYUP && 

if (NULL == pkrn) 

lpmsg->message 1= WM SYSKEYDOWN && 

return FALSE; /* No memory. */ 

lpmsg->message != WM_SYSKEYUP) 

pkrn->pkrnNext = pkrnHead; /* Link. */ 

goto LCal 1 Next ; /* Not a keyboard message. */ 

pkrnHead = pkrn; 

if (lpmsg->wParam >= 256) 

} 

goto LCal1 Next ; /* Bogus key code. */ 

pkrn->kri = ‘lpkri; 
return TRUE; 

GetKeyMsg(key, lpmsg->wParam, 1 pmsg->lParam) ; 
if (NULL == (ppkrn = PpkrnFind(&key ))) 

} 

goto LCal 1 Next; /* Key is not mapped. */ 

BOOL WINAPI _export FGetKri ( LPKRI lpkri) 

/*********************************★*★******★********** j 

if ( WM_KEYDOWN == lpmsg->message II 

/* -- Return the key mapping, if found. */ 

WM_SYSKEYDOWN == lpmsg->message) 

/* -- lpkri : keyFrom is key to find, fill rest. */ 

BSetVkct(*ppkrn)->kri.keyTo.vkc, 

/*****************************************************/ 

BSetVkctkey.vkc, 0)); 

{ 

else 

BSetVkc((*ppkrn)->kri.keyTo.vkc, 0); 

KRN “ppkrn; 

if (NULL != (ppkrn = PpkrnFind(&lpkri->keyFrom))) 

lpmsg->wParam = (*ppkrn)->kri.keyTo.vkc; 

{ 

1pmsg->lParam = (lpmsg->lParam & ~0x01ff0000) 1 

‘lpkri = (‘ppkrn)->kri ; 

( (long)(*ppkrn)->kri.keyTo.wExt « 16); 

return TRUE; 

} 

return FALSE; 

LCal 1 Next: 

return CallNextHookExthhok, code, wParam, 

(LPARAM)Ipmsg); 

} 

} 

BOOL WINAPI _export FNextKri(LPKRI lpkri. LPKEY lpkey) 

/*****************************************************y 

KRN **PpkrnFind(LPKEY lpkey) 

/A****************************************************/ 

/* -- Return the mapping following given, else head. */ 
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it in response to the UM_NCPAINT message, after you have 
passed that message to DefUindowProcO. 

You will need to use GetUindowDCO instead of GetDCO 
when painting, so that your border will not be clipped to 
the listbox's client area. When you use such a display con¬ 
text, the coordinate (0, 0) corresponds to the upper left- 
hand corner for the entire window. You can determine the 
position of the border by calling GetUindowRectO for the 
listbox, which returns a rectangle in screen coordinates, 
then subtracting the upper left position from the lower 
right to get the dimensions of the entire listbox window. If 
you called those coordinates ( dx, dy), the border could then 
be drawn inside the rectangle (0, 0, dx, dyi. 

You should continue to use the US_B0RDER style when 
you create the window, otherwise De¬ 
fUindowProcO will not allow room for 
the borders in the non-client area. If 
flashing is a problem (DefUindowProcO 
draws the borders when you call it 
from your UM_NCPAINT handler, then 
you redraw then) turn the US_B0RDER 
style off before calling DefUindowProcO 
and restore it after the call. You can 
do this with GetUindowLongO and Set- 
UindowLongO, specifying the GUL_STYLE 
offset. 



/* -- Ipkey : Find first if null, else following. */ 
/* -- lpkri : Filled on output. */ 

^ ****** ****** ********** ******** ********** ****** ******* i 
{ 

KRN **ppkrn; 

if (NULL == pkrnHead) 

return FALSE; /* No mappings at all. */ 
if (NULL == Ipkey II 
NULL == (ppkrn = PpkrnFind(1pkey)) II 
NULL == *(ppkrn = &(*ppkrn)->pkrnNext)) 
ppkrn = ApkrnHead; 

*1pkri = (*ppkrn)->kri; 


Q I want to convert the Enter key 
in the bottom right of my key¬ 
board into a Tab key. How can I do 
this? Do I have to use keyboard 
hooks or the DDK? 

Luis Castro 
lccastro@cic.itcr.ac.cr 

A You are on the right track - you 
do need a hook, but not a key¬ 
board hook. Even though a keyboard 
hook is invoked every time GetMes- 
sageO or PeekMessageO returns a key¬ 
board message, the hook procedure 
cannot modify the keyboard mes¬ 
sage. Ail a keyboard hook can do is 
examine the message, and if it 
wishes, eat it. There is a hook that 
provides the desired functionality, 
however - the message hook. 

A message hook gets called 
whenever GetMessageO or PeekMes¬ 
sageO returns a message to a task. 
The hook gets called from within 
GetMessageO or PeekMessageO before 
either actually returns. This type of 
hook is passed a pointer to the mes¬ 
sage structure, which it can modify at 
will. So you can write a message 
hook procedure that looks for key¬ 
board messages, checks to see if any 
are for the numeric keypad Enter 
key, and modifies those that are. 


WHEN THE DEBUGGING GETS TOUGH... 
REACH FOR ONE OF PERISCOPE'S 
"BUTT-SAVIN G" DEBUGGERS. 

"Great product, has already 
saved my butt more than once, 
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Just push the "panic button" on the break-out switch I comes with all Peri scopes! 
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■ Use Periscope/32 to debug system- 
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3.x, OS/2 2.x, or your own 32-bit 
operating environment. 


RENT OR BUY THE 

HARDWARE when you 
need the power of an ICE... 

■ The Periscope Model IV hardware 
adds the power of an ICE to both 
Periscope/EM and Periscope/32. Debug 
hardware interrupts, communications 
software, real-time software, and in any 
situation where you need zero slow¬ 
down, no-impact tracing or monitoring. 
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Listing 2 continued 


return TRUE; 
} 



BOOL WINAPI _export FRemoveKeytLPKEY Ipkey) 

/★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★■A:****************/ 

/* -- Remove the given key map, if it exists. */ 

/* -- lpkri : Map to remove. */ 

I *****************************************************i 
{ 

KRN **ppkrn, *pkrn; 


if (NULL != (ppkrn = PpkrnFind(1pkey))) 

{ 

pkrn = *ppkrn; 

*ppkrn = (*ppkrn)->pkrnNext; /* Unlink. */ 
LocalFree((HLOCAL)pkrn); 
return TRUE: 

} 

return FALSE; 

} 


void WINAPI _export ResetMap(void) 

I* -- Remove all key mappings. */ 

jj 
{ 

KRN *pkrn, *pkrnNext; 


for (pkrn = pkrnHead; NULL != pkrn; 
pkrn = pkrnNext) 

{ 

pkrnNext = pkrn->pkrnNext; 

LocalFree((HLOCAL)pkrn); 

} 

pkrnHead = NULL; 

} 

/* End of File */ 


Each of the various keyboard messages comes with 
certain data in wParam and IParam. wParam contains the vir¬ 
tual key code, while IParam contains additional data about 
the keystroke that generated the message (such as the 
scan code and the 'extended key' bit: see Table 1). The 
combination of the scan code and extended bit uniquely 
identifies a key on the keyboard. The virtual key code 
represents the ANSI character synthesized from the key¬ 
stroke^). Mapping one key to another requires modifica¬ 
tion of the virtual key code, scan code, and the extended 
bit in a keyboard message. 

You have to be careful which keyboard messages you 
map, however. Some keyboard messages are placed in 
the system queue by the keyboard driver, while others are 
synthesized from those messages by Windows. The key¬ 
board driver enqueues only key-down and key-up mes¬ 
sages (UM_KEYDOUN, UM_SYSKEYDOUN, UM_KEYJP, and klM_SYSKEYUP), 
and these are the only messages that should be mapped. 
This is because Windows will end up generating the syn¬ 
thesized messages from the message-hook-modified ver¬ 
sions of the driver-enqueued messages. 

Another issue related to message synthesis is the state 
of the keyboard when Windows generates the message. 
An example will help illustrate the problem. Suppose the 
user has pressed the Shift key, followed by the 'A' key, to 
generate an upper-case 'A'. Also assume the task has a 
typical message loop: 

while (GetMessage(&msg, 0, 0, 0)) 

{ 

T ranslateMessage(&msg); 

DispatchMessage(&msg); 

} 


Listing 3 remap.c — Remapping application 


! *★★★★★★★★★★★★*★★★★★★***★★****★★*★***★★*★*★★★**★★★★**★ j 

switch (wm) 

/* remap.c */ 

{ 

/* -- Program performs keyboard remapping. */ 

default: 

/* -- To build: cc -d -DSTRICT remap.c keymap.lib */ 

break; 

/★★★★★★★★★★★★★★★It*************************************/ 


((include <windows.h> 

case WM GETDLGCODE: 

((include <windowsx.h> 

return DLGC WANTARROWS 1 DLGC WANTTAB | 

#include "remap.h" 

DLGC WANTALLKEYS; 

(/include "keymap.h" 



case WM SETTEXT: 

const KRI kriNull; 

case WM SETFOCUS: 


case WM KILLFOCUS: 

BOOL CALLBACK export FDlgProctHWND hwnd, 

InvalidateRect(hwnd, NULL, TRUE); 

UINT wm. WPARAM wParam. LPARAM IParam); 

break; 

LRESULT CALLBACK _export LwKeyProctHWND hwnd. 


UINT wm, WPARAM wParam, LPARAM IParam); 

case WM LBUTTONDOWN: 

void UpdateDlgtHWND hwnd, KRI *pkri); 

SetFocus(hwnd); 


return 0; 

LRESULT CALLBACK _export LwKeyProctHWND hwnd, 


UINT wm, WPARAM wParam, LPARAM IParam) 

case WM KEYDOWN: 

/*****************************************************/ 

case WM SYSKEYDOWN: 

/* -- Custom control gathers virtual keycodes. */ 

GetKeyMsgtkey, wParam, IParam); 

/*****************************************************/ 

SendMessage(GetParent(hwnd), WM COMMAND, 

{ 

GetWindowWord(hwnd, GWW ID), 

PAINTSTRUCT wps; 

MAKEL0NG(hwnd, &key)); 

RECT rect; 

szBuf[0] = (BYTE)wParam; 

char szBuf[2]; 

SzBuf[l] = 0; 

KEY key; 

SetWindowTextthwnd, szBuf); 
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The first message returned will be a HM_KEYDOUN for the 
Shift key, which TranslateMessageO will ignore (UM_CHAR 
messages are not generated for the Shift key). The next 
message will be a HM_KEYDOUN for the 'A' key. When Trans¬ 
lateMessageO sees this, it will enqueue a UM_CHAR message 
(using PostMessageO ) with the virtual key code for an up¬ 
per-case "A". DispatchMessageO will dispatch the MM_KEYDOMN 
for the 'A' key, and the next call to GetMessageO will re¬ 
turn the synthesized UM_CHAR, even though there are a pair 
of UM_KEYUP messages still in the system queue. The reason 
this works is that: 

• hardware messages are not actually moved from the 
system queue to a task queue, but are directly re¬ 
moved from the system queue, 

• posted messages (the MM_CHAR) are placed directly in the 
task queue, and 

• the task queue is emptied before the system queue. 

The issue involves the message synthesis in Translate¬ 
MessageO. When it sees a MM_KEYDOUN message for the "A' 
key, it must check if a modifier key such as Shift is cur¬ 
rently depressed. It does this by consulting the key state 
map, which contains the state of all 256 virtual keys in an 
array of 256 bytes. The most significant bit is set while a 
key is down, and is clear otherwise. Windows maintains 
this map as keys are pressed and released. So if Translate¬ 
MessageO sees that the high bit of the 16th byte in the key 
map is set (16 is the virtual key code for the Shift key), it 
knows to generate a UM_CHAR for upper-case 'A' instead of 
lower-case 'a'. 

But suppose the hook procedure has remapped the 
Shift key to be some other key. In this case, it is inappro¬ 
priate for TranslateMessageO to generate a MM_CHAR for up¬ 
per-case 'A'. The implication is that the message hook 


Listing 3 continued 


break; 

case WM_PAINT: 

BeginPaint(hwnd, &wp$); 

GetWindowTextthwnd, szBuf, 2); 
GetClientRectihwnd, Hrect); 
SelectObjecttwps.hdc. 

GetStockObject(NULLJIRUSH)); 
DrawText(wps.hdc, szBuf, -1, Arect, 

DT_CENTER | DTJINGLELINE I DTJCENTER); 
Rectangleiwps.hdc. rect.left, rect.top, 
rect.right, rect.bottom); 
if (GetFocusO == hwnd) 

{ 

InflateRectt&rect, 

-GetSystemMetrics(SM_CXBORDER), 
-GetSystemMetrics($M_CYBORDER)); 
DrawFocusRecttwps.hdc, Arect); 

} 

EndPaintthwnd, Awps); 
return 0; 

} 

return DefWindowProcthwnd, wm, wParam, IParam); 

) 

int PASCAL WinHain(HINSTANCE hins, HINSTANCE hinsPrev, 
LPSTR lpsz. int wShow) 
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must also manipulate the state of the key map. If the 
message hook alters a keyboard message, it must also 
clear the high bit of the original message's virtual key 
code entry in the key map and set the high bit of the new 
virtual key code entry. 

I wrote a DLL (keymap.dll) that provides a generalized 
key mapping interface. Its API is defined in keymap.h (List¬ 


ing l), which defines two data structures for describing a 
key mapping. The first, of type KEY, consists of a virtual 
key code (vkc member) and a UINT (wExt member) to con¬ 
tain the scan code and extension bit. These two fields of 
the KEY data structure contain all the key-dependent infor¬ 
mation present in any keyboard message. So a pair of 
KEYs can be used to define a mapping, one KEY for the key 


Listing 3 continued 


/* -- Entry point. */ 

case cidTo: 


kri.keyTo = *(KEY *)HIWORD(1Param); 

t 

UpdateDlgthwnd, &kri); 

if (NULL == hinsPrev) 

{ 

WNDCLASS wcs; 

break; 

case IDOK: 

if (IFSetKri(&kri)) 

wcs.style = 0; 

MessageBox(hwnd, "Can't set mapping". 

wcs.lpfnWndProc = LwKeyProc; 

"Map Key", MB OK); 

wcs.cbClsExtra = 0; 

break; 

wcs.cbWndExtra = 0; 


wcs.hlnstance = hins; 

case cidClear: 

wcs.hlcon = NULL; 

FRemoveKeytJkri.keyFrom); 

wcs.hCursor = LoadCursor(NULL, IDC ARROW); 

if (IFNextKri(Akri, &kri.keyFrom)) 

wcs.hbrBackground = (HBRUSHMCOLOR WINDOW + 1); 

kri = kriNull; 

wcs.lpszMenuName = NULL; 

UpdateDlgthwnd, &kri); 

wcs.lpszClassName = szKeyClass; 

break; 

if (IRegisterClass(&wcs)) 


return FALSE; 

case cidClearAll: 

} 

ResetMapO; 
kri = kriNull; 

DialogBoxthins, MAKEINTRESOURCE(dlgMap), NULL, 

UpdateDlgthwnd, &kri); 

FDlgProc); 

break; 

return 0; 


} 

case cidNext: 

FNextKri(&kri, &kri.keyFrom); 

BOOL CALLBACK export FDlgProc(HWND hwnd. 

UpdateDlgthwnd, &kri); 

UINT wm. WPARAM wParam, LPARAM IParam) 

break; 

j 


1* -- Key mapping dialog procedure. */ 

case IDCANCEL: 

/***************************************************** j 

EndDialogthwnd, wParam); 

{ 

return TRUE; 

static KRI kri; 

} /* End switch wParam. */ 
break; /* End case WM COMMNAND. */ 

switch (wm) 

{ 

default: 

} /* End switch wm. */ 

return FALSE; 

break; 

} 

case WMJNITDIALOG: 

void UpdateDlg(HWND hwnd, KRI *pkri) 

kri = kriNull; 

/*****************************************************^ 

FNextKri(&kri, NULL); 

/* -- Update the dialog controls with the new kri. */ 

UpdateDlgthwnd, &kri); 

/*****************************************************y 

return TRUE; 

{ 

char szBuf[5]; 

case WM ACTIVATE: 


FMapEnable(0 == wParam); 

szBufCl] = 0; 

break; 

szBuf[0] = (BYTE)pkri->keyFrom.vkc; 

SetDlgltemTextthwnd, cidFrom, szBuf); 

case WM_COMMAND: 

szBuf[0] = (BYTE)pkri->keyTo.vkc; 

switch (wParam) 

SetDlgltemTextthwnd, cidTo, szBuf); 

{ 

SetDlgltemlntthwnd, cidFromNum, pkri->keyFrom.vkc, 

default: 

FALSE); 

break; 

SetDlgltemlntthwnd, cidToNum, pkri->keyTo.vkc, 

FALSE); 

case cidFrom: 

wsprintf(szBuf, "0x!Ex", (UINT)pkri->keyFrom.wExt); 

kri.keyFrom = *(KEY *)HIWORD(1Param); 

SetDlgltemTextthwnd, cidScanFrom, szBuf); 

if (1FGetKri(&kri)) 

wsprintftszBuf, "0x!6x", (UINT)pkri->keyTo.wExt); 

kri.keyTo = kriNull.keyTo; 

SetDlgltemTextthwnd, cidScanTo, szBuf); 

UpdateDlg(hwnd, &kri); 

} 

break; 

/* End of File */ 
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to map, and the other KEY for the target key. The next 
data structure in keymap.h, of type KRI, defines such a map¬ 
ping by containing a keyFrom member and a keyTo mem¬ 
ber. 

keymap.h also contains the prototypes for the six func¬ 
tions exported by the DLL FSetKriO installs the mapping 
specified by the given KRI. FGetKriO searches for a given 
mapping. You specify the source key in the keyFrom field of 
a KRI, and if the mapping exists, FGetKriO fills the keyTo 
field with the target key. FNextKriO is used to iterate 
through the list of key mappings. It accepts a far pointer 
to a KRI (lpkri) and a far pointer to a KEY (lpkey). If a map¬ 
ping from *lpkey exists, the routine returns the next map¬ 
ping in *lpkri, otherwise it returns the first mapping. If the 
lpkey parameter is NULL, FNextKriO returns the first map¬ 
ping. FRemoveKeyO accepts an lpkey parameter, and if a 
mapping from *lpkey exists, it is removed. FMapEnableO dis¬ 
ables or re-enables all key mappings, and ResetMapO re¬ 
moves all mappings. At the end of keymap.h is a conven¬ 
ience macro that fills in a KEY data structure given a key¬ 
board message's wParam and IParam. 

The DLL is implemented in keymap.c (Listing 2). It main¬ 
tains the list of mappings as a singly-linked list using the 
data structure KRN. This data structure consists merely of a 
pointer to the next KRN and a KRI mapping. The global 
variable pkrnHead is a pointer to the head of the list. Nodes 
are allocated from the DLL's local heap, so I can use near 
pointers to KRNs. 


Listing 4 

remapper 

remap, rc —- Dialog for keyboard 

/*****************************************************/ 

/* remap.rc 

*1 

/* -- Dialog for keyboard remapping app. */ 

! **★★★★***★*★★★★★★★★★★*★★★**★★★★★★★***★★*★**★★★★*★★*★★ j 

include <windows.h> 

frinclude "remap.h 


dlgMap DIALOG 6, 

18, 212, 48 

STYLE DS MODALFRAME I WS POPUP I WS VISIBLE I 

WS CAPTION 1 WS SYSMENU 

CAPTION "Map Key" 


FONT 8. "MS Sans Serif" 

BEGIN 


LTEXT 

"AKeyboard Key:", -1, 2, 4, 52, 8 

CONTROL 

cidFrom, szKeyClass, WS TABSTOP, 


56, 2, 16, 12 

LTEXT 

cidFromNum, 76, 4. 20, 8 

LTEXT 

"Scan Code:", -1, 106, 16, 42, 8 

LTEXT 

cidScanFrom, 150, 4, 20, 8 

LTEXT 

"ARemapped To:", -1, 2, 16, 52, 8 

CONTROL 

cidTo, szKeyClass, WS TABSTOP, 


56, 14, 16, 12 

LTEXT 

cidToNum, 76, 16, 24, 8 

LTEXT 

"Scan Code:", -1. 106, 4, 42, 8 

LTEXT 

cidScanTo, 150, 16, 20, 8 

DEFPUSHBUTTON 

"ASet", IDOK, 2. 32, 40, 14 

PUSHBUTTON 

"AC 1 ear", cidClear, 44, 32, 40, 14 

PUSHBUTTON 

"Clear AA11”, cidClearAll, 


86, 32, 40, 14 

PUSHBUTTON 

"ANext", cidNext, 128, 32, 40, 14 

PUSHBUTTON 

"ADone", IDCANCEL, 170, 32, 40, 14 

END 
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Figure 1 Keyboard remapping application 


The DLL's LibMainO initialization routine calls FMapEn- 
ableO with the fEnable parameter set to TRUE, which causes 
FMapEnableO to install the message hook. FMapEnableO uses 
SetUindowsHookExO to install the message hook procedure; 
it receives back an HHOOK, which it stores in the global vari¬ 
able hhok. If FMapEnableO sees that hhok is not NULL, it by¬ 
passes the call, since a hook has already been installed. 
Similarly, if the fEnable parameter is FALSE, FMapEnableO will 
call UnhookUindowsHookExO (to remove the hook) only if the 
message hook is currently installed (hhok is not NULL). The 
new state of the hook procedure (installed or not) is re¬ 
turned, allowing the client to detect failure in the case 
when SetUindowsHookExO returns NULL. The DLL's UEPO func¬ 
tion calls FMapEnableO, passing FALSE to remove the mes¬ 
sage hook procedure. 

The next routine in the listing is the hook procedure, 
LwMsgHookO. Windows calls this routine just before GetMes- 
sageO or PeekMessageO returns a message to any task in 
the system. This system-wide behavior is specified when 
you call SetUindowsHookExO to install the hook procedure. 
SetUindowsHookExO accepts a task handle parameter, htask, 
which, if NULL, means a system-wide hook should be in¬ 
stalled. Otherwise, if htask contains a valid task handle, 
the hook is installed for that task only, i am assuming that 
you want a system-wide hook, but if not, you can have 
FMapEnableO call GetCurrentTaskO to get the client task's 
task handle for the call to SetUindowsHookExO. If you want 
to provide keyboard mapping to multiple specific clients 
simultaneously, then you will have to maintain multiple 
HHOOK values in keymap.dll. But if you only want keyboard 
mapping for one application, then you don't need a DLL 
at all, and you can embed LibMainO 's code in your initiali¬ 
zation routine and the UEPO's code in your termination 
routine, and just link with the code keymp.c. A DLL is only 
required for a system-wide hook. 

LwMsgHookO first performs a series of checks to see if the 
current message is one that should be remapped. If the 
'code' parameter is less than 0, the routine jumps to the 
label LCallNext, which passes the message to the next 
hook in the chain via CallNextHookExO. This is in accord¬ 
ance with the SDK documentation, which notes that "if the 
code parameter is less than zero, the callback function 
must pass the message to CallNextHookEx without further 
processing and return the value returned by CallNex¬ 
tHookEx.' 

LwMsgHookO then tests to see if the message is one of 
the four keyboard-driver-enqueued messages, chaining to 
the next hook if not. The next test is a sanity check to 


ensure that a message with a bogus virtual key code will 
not be processed. After all, there is nothing to prevent a 
buggy application from posting a bogus keyboard mes¬ 
sage. 

The utility routine PpkrnFindO is used to see if the given 
keyboard message has a mapping. Instead of returning a 
KRN pointer, PpkrnFindO returns a pointer to the link 
pointer to the node, (which will simplify unlinking). If the 
mapping exists, a pointer to the node's predecessor's next 
pointer is returned (or a pointer to pkrnHead for the first 
node on the list). If no mapping is found, NULL is returned, 
and LwMsgHookL) chains to the next hook. 

if the preceding tests were passed, then a mapping for 
the key has been found. LwMsgHookO then uses the utility 
function BSetVkcO to keep the key map in sync with the 
key's mapping. If the current message is UM_KEYDOUN or 
UM_SYSKEYDOUN, the original virtual key code entry is set to 
the 'up' state, and the new virtual key code entry is set to 
whatever value the key map contained for the original 
key. If the current message is UM_KEYUP or UM_SYSKEYUP, the 
corresponding key map entry is set to the 'up' state, since 
Windows will not do this for you. 

LwMsgHookO then sets the messages's virtual key code, 
scan code, and extended bit to the values specified in the 
mapping's keyTo data structure, and passes the message 
on to the next hook. 

The remaining routines are those defined in keymap.h. 
At the start of FSetKriO is a check that disallows mapping 
to or from the Alt key. Mapping the Alt key is problematic, 
since any keyboard message generated while the Alt key 
is depressed will be a UM_SYSxxx variant. Not only would 
you have to map the virtual key code, scan code, and 
extended bit, you would also have to alter the actual mes¬ 
sage numbers. Moreover, Windows apparently maintains 
the state of the Alt key internally in addition to its state in 
the key map. I tried to map arbitrary keys to the Alt key 
without success, even though I was translating the mes¬ 
sages, codes, extended bit, and key map correctly. I think 
you would have to resort to undocumented functionality 
to map to the Alt key - probably not a good thing to do 
given that the next version of Windows is looming on the 
horizon. So, I did what any respectable programmer in this 
situation would do: I punted Alt key mapping. 

FSetKriO next calls PpkrnFindO to see if a mapping al¬ 
ready exists for the source key. If not, a new node is allo¬ 
cated and inserted at the head of the list; otherwise the 
current mapping is reused. The contents of the mapping 
are then set to the value of the input KRI. The only way 
this routine can fail is if LocalAllocO fails. 

FGetKriO uses PpkrnFindO to find the mapping given by 
lpkri->keyFrom. If found, the mapping is set into the 
passed-in KRI. FNextKriO first examines pkrnHead to see if 
there are any mappings at all, and returns FALSE if not. 
Otherwise, if no source key is specified, or the source key 
is not mapped, or the mapping is the last in the list, 
FNextKriO returns the first mapping; else, the next. 

FRemoveKeyO locates the given mapping with a call to 
PpkrnFindO. If one is found, it is unlinked from the list and 
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the node memory is freed. Finally, ResetMapO frees all 
nodes in the list. 

I also wrote a program that uses keymap.dll to let the 
user enter key mappings, remap.exe is implemented in re¬ 
map. c (Listing 3), remap, rc (Listing 4), and remap, h (Listing 5). 
This program uses a dialog box as its main window (see 
Figure 1). The dialog consists of a source key area (the 
'From' group box), a target key area (the "To' group box), 
and a series of pushbuttons. Each key area contains a cus¬ 
tom control that accepts a single keystroke and displays 
the character corresponding to the virtual key code, a 
static text that displays the numeric virtual key code, and 
a static text that displays both the scan code and ex¬ 
tended bit. The pushbuttons allow the user to set a new 
mapping, clear the currently displayed mapping, clear all 
mappings, show the next mapping, and terminate the dia¬ 
log box. 

The custom control behaves something like a simple, 
one-character edit box, except that instead of reacting to 
UM_CHAR messages, this control reacts to UM_KEYDOUN mes¬ 
sages. Also, the control grabs all keyboard input, including 
Tab keys, Enter keys, and arrow keys, which does hamper 
keyboard navigation in the dialog if a custom control has 
the focus, but is a necessary evil in order to allow the user 
to specify those keys. 

The custom control's window procedure is LwKeyProcf). 
It responds to the UM_GETDLGCODE message with a set of bit 
flags that tell Windows to send all keyboard input to the 
control. The window procedure has a case for the UM_SET- 
TEXT message to invalidate its client area and refresh its 
display. Windows does not automatically generate a 
UM_PAINT message when a window's text is changed. 
LwKeyProof) treats UMJETFOCUS and UM_KILLFOCUS messages 
similarly, so that the caret will be displayed or removed 
when the control updates. On receipt of a left mouse 
down (UM_LBUTTONDOUNi, LwKeyProcf) gives itself the focus by 
calling Set Focus (). 

LwKeyProcO takes note of keystrokes when it receives 
a UM_KEYDOUN or UM_SYSKEYDOWN message. LwKeyProcf) uses the 
utility macro GetKeyMsgf), defined in keymap.h (Listing 5), to 
fill a KEY structure from the wParam and IParam parameters 
that accompany the message. The control sends a UM_COM¬ 
MAND message to its parent (the dialog), but instead of 
packing a notification code into the high word of IParam, it 
supplies the address of the KEY structure. Posting the 
UM_COMMAND would not have worked, since by the time it 
was received, the address of the KEY structure would be 
invalid. Even though controls usually notify their parents 
by posting UM_COMMAND, it is perfectly legal to send the mes¬ 
sage, at the expense of more stack space. The last action 
taken for UM_KEYDOUN and MM_SYSKEYDOMN is to update the 
control's text to the single character obtained from the 
keystroke. 

The last message handled by LwKeyProcf) is UM_PAINT. 
The control obtains the size of its client area and its single 
character of window text. It uses DrawTextf) to display the 
character. This is a convenient text output routine to use 
since it lets you center the text both vertically and hori¬ 
zontally, by specifying the DT_CENTER and DT_VCENTER flags. 


After selecting a NULL brush into the device context ob¬ 
tained from BeginPaintf), LwKeyProcf) then calls Rectanglef) 
to draw an outline for the control. The NULL brush prevents 
Rectanglef) from filling the interior. Finally, if the control 
has the focus, it indents the client area rectangle by one 
border unit on each side and calls DrawFocusRectf) to dis¬ 
play a caret. 

Since a dialog is being used for the main window, Uin- 
MainO's job is easy. It registers a class for the custom con¬ 
trol (I gave it a class name of 'ReMap'), and calls Dialog- 
Boxf) to invoke the dialog. The dialog procedure, 
FDlgProcf), is the next procedure in the file. It maintains a 
static KRI that is updated as the user changes fields in the 
dialog. FDlgProcf)'s UM_INITDIALOG code clears the static KRI 
and calls FNextKrif) to obtain the first mapping, in case 
some other client of keymap.dll has previously installed a 
mapping. If no mapping is found, then the contents of the 
KRI will be left clear. The utility routine UpdateDlgf) is then 
called to update all dependent fields in the dialog from 
the value of the static KRI. 

As keymap.dll is currently implemented, it is possible to 
have multiple instances of remap.exe running. However, 
there is no provision for updating the contents of in¬ 
stances of remap.exe when a mapping is changed in one of 
them. For example, if there is one instance, A, with a sin¬ 
gle mapping defined, and another instance, B, is created, 
B will show A's mapping. But if A is then used to remove 
the mapping, B will continue to show the mapping, even 
though it no longer exists. I didn't add code to notify all 
instances since I think it will be rare to want more than 
one instance. If for some reason you want to support mul¬ 
tiple instances of remap.dll, you can use SendMessagef) with 
a window handle of HMNDJROADCAST to send a special mes¬ 
sage to all top-level windows. You would then add a case 
to FDlgProcf) to update the dialog when such a message is 
received. 

Whenever the dialog is activated, FDlgProcf)'s UM_EN- 
ABLE case disables the message hook, so that the user 


Listing 5 remap.h — Dialog constants for 
keyboard remapper 


1 * remap.h 

*/ 

/* -- Dialog constants for keyboard remapping demo. */ 


//define dlgMap 

ION 

//define cidFrom 

1001 

i/define cidFromNum 

1002 

//define cidScanFrom 

1003 

//define cidTo 

1004 

//define cidToNum 

1005 

//define cidScanTo 

1006 

//define cidMap 

1007 

//define cidClear 

1008 

//define cidClearAll 

1009 

//define cidNext 

1010 

//define szKeyClass 
/* End of File */ 

"KeyClass" 
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can interact with the dialog using unaltered keystrokes. 
The hook is reenabled when the dialog is deactivated. 

FDlgProcO's UM_COMMAND code is an embedded switch 
statement, with a case for each of the dialog's two custom 
controls and for each pushbutton. The cidFrom case, which 
handles notifications from the source key, stores the KEY 
value supplied by the custom control into the keyFrom 
member of the dialog's static mapping variable, and calls 
FGetKriO to fill in the fields for the rest of the mapping, if 
one exists. UpdateDlgO is then called to update the dialog 
to reflect the mapping. The cidTo case is simpler, it han¬ 
dles notifications from the target custom control, and as¬ 
signs the KEY value to the keyTo target member of the 
static mapping before refreshing the dialog. 

The IDOK notification is received when the "Set" push¬ 
button is pressed. The code installs the current mapping 
and displays a message box if FSetKriO failed. The next 
case handles a push of the 'Clear' pushbutton by remov¬ 
ing the current mapping. It then calls FNextKriO, followed 
by UpdateDlgO, to display the next mapping if there is one. 
The cidClearAll case handles the "Clear All' pushbutton by 
calling ResetMapO, setting the static mapping to the empty 
mapping (since there are none to display), and calling Up¬ 
dateDlgO to show the empty dialog. In response to a push 
of the 'Next' pushbutton, the cidNext case calls FNextKriO 
then makes the obligatory call to UpdateDlgO. Finally, re¬ 
ceipt of IDCANCEL signifies that the user is dismissing the 
dialog, so EndDialogO is called to terminate it. 
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Driver Bug of the Month 

Even though with each release of Windows, Microsoft 
fixes more bugs in the Windows code base, Windows ap¬ 
plications continue to be at the mercy of buggy device 
drivers. Flardware vendors write device drivers at an 
amazing rate, to support the growing array of peripherals 
available under Windows. But far too often, the device 
drivers they release on an unsuspecting public are buggy. 
Bugs in such a low-level component of the Windows oper¬ 
ating system can have devastating effects on applications 
using the underlying device, and to the user it appears 
that the application is at fault. All too often I have had a 
buggy device driver generate a GP fault inside its DLL, 
only to have Windows report to the user that my applica¬ 
tion caused a UAE inside the driver module. 

This month I would like to introduce what I hope be¬ 
comes a regular feature of the Q8A, namely the Windows 
device driver 'Bug of the Month.' Anyone who has done 
more than introductory programming with Windows has 
likely had to work around bugs in hardware vendors' de¬ 
vice drivers; I know I have. Each installment will describe 
the bug and a way to work around it, if known. By featur¬ 
ing a different bug each month, my hope is to make you 
aware of the problems, so that you can watch out for 
them in your configuration tests, and use any existing 
workarounds. 

If you have a favorite device driver bug that you have 
already had to work around in your application, I would 
love to hear from you. To get the ball rolling, let me start 
with a bug in the standard Windows VGA driver, vga.drv. 

The problem occurs when you obtain a device-depen¬ 
dant bitmap (DDB) from a small, 4-bit, run-length encoded 
device-independent bitmap (DIB) using SetDIBitsO. If the 
biClrUsed field of the BITMAPINFOHEADER in the DIB is 0, Set¬ 
DIBitsO will GP fault inside the VGA driver. The online 
SDK documentation for the BITMAPINFOHEADER data structure 
has this to say of the biClrUsed field: 'Specifies the number 
of color indexes in the color table actually used by the 
bitmap. If this value is zero, the bitmap uses the maximum 
number of colors corresponding to the value of the biBit- 
Count member.' So 0 is a legal value. 

What's happening is that the VGA driver is erroneously 
assuming that if the biClrUsed field is 0, then the DIB con¬ 
tains a 256-color table, even though each pixel in the DIB 
is only 4 bits deep! As a result, it tries to read all 256 
RGBQUADs out of the color table, and if the size of the global 
memory block enclosing the DIB is smaller than 1024 
bytes (256 * 4), kaboom! The interesting thing about this 
bug is that if your DIB is greater than 1 Kb, the final result 
is fine, since subsequent driver code will read the DIB bits 
from the proper location in the DIB, overwriting the bogus 
entries in the color table. 

Fortunately, it is easy to bulletproof your application 
against this bug. Before any call to SetDIBitsO, if the BIT¬ 
MAPINFOHEADER s biClrUsed member is 0, and the biBitCount 
member is less than 24, set the biClrUsed member to: 

1 « biBitCount 
□ 
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Industry-Related News & Announcements 


Ontrack Updates Online DOS Reference 

TechSource for DOS is a hypertext database resource 
published using the Folio VIEWS engine. Designed for 
technical support and computer repair technicians, Tech- 
Source for DOS provides access to information about 
hardware, software, product histories, field reports, and 
operating systems, both current and out-of-date versions. 
This version of the product includes DiskSource, a hard 
disk drive and controller encyclopedia, and System- 

LPA Prolog Gets Graphic Improvements 

LPA Prolog for Windows is a 32-bit Windows 3.1 de¬ 
velopment environment available in a Programmer Edi¬ 
tion (includes all the built-in predicates, development 
environment, debugger, documentation, and two-way 
DLL interface) and a Developer Edition (includes a run¬ 
time generator for producing standalone applications). 

The new version of LPA Prolog for Windows features di¬ 
rect access to Windows graphics functions and a declara¬ 
tive graphics description language, as well as an 

EMS Updates C/C++ Utility CD-ROM 

EMS Professional Shareware is shipping an updated 
version of its C/C++ Utility Library on CD-ROM. The li¬ 
brary now contains 1,090 public domain and shareware 
products for programmers using C++, Microsoft C and 
Turbo C. All products in the library are described in an in¬ 
cluded indexed database which you can search by ven¬ 
dor, name, type, release date, or free text across 
descriptions. Categories of software in the package in¬ 
clude: benchmarking, binary trees, bit manipulation, com¬ 
munications, compression, databases, debugging, disk 


Source, a reference to computer system boards, includ¬ 
ing jumper settings and BIOS information. 

TechSource for DOS costs $799; quarterly updates 
cost $65 per year. DiskSource and SystemSource can be 
purchased separately for $99 and $199 respectively. For 
more information, contact Ontrack Computer Systems, 
6321 Bury Drive, Eden Prairie, MN 55346, (800) 752- 
1333 or (612) 937-1107; fax(612) 937-5815. 


interface to Visual Basic, Excel, and Word via a configur¬ 
able DDE toolkit. 

LPA Prolog for Windows v2.5 costs $745, or $1,495 
for the Developer Edition. For more information, contact 

Logic Programming Associates Ltd., Studio 4, Royal Victo¬ 
ria Patriotic Building, Trinity Road, London SW18 3SX, 
England, 081 871 2016;fax 081 874 0449; Internet 
lpa@dx.compulink.co.uk; AppleLink UK0049. 


management, graphics, help, I/O, internationalization, 
mathematics, memory management, pen computing, 
printing, security, sorting, text processing, translation, 
and more. 

The C/C++ Utility Library costs $59.50 on CD-ROM or 
$149 on diskettes. For more information, contact EMS 

Professional Shareware, 4505 Buckhurst Ct, Olney, MD 
20832-1830, (301) 924-3594;fax (301) 963-2708; 
Internet eengelmann@worldbank.org. 


Improved Boot Software Offers Task Scheduling 


BOOTCON is a configuration utility that lets the user 
select a different startup (autoexec.bat, config.sys, etc.) en¬ 
vironment from a menu at boot time. BOOTCON can 
give applications more memory by allowing drivers and 
TSRs to be loaded only when they are needed. The pro¬ 
gram supports up to 100 configurations, including multi¬ 
ple Windows configurations. You can use the product to 
add, delete, copy, rename, edit, and view configurations 
interactively. 

The new version includes a scheduler, automatic ar¬ 
chiving, and configuration comparison. The new sched¬ 
uler lets you designate tasks to be automatically 
performed at a specific time. For example, you could use 
the scheduler to reboot the system each night into a 
'dean' configuration, do disk defragmentation, then re¬ 


boot back into the original Windows configuration, all 
with no user intervention. Automatic archiving means 
that if you make some change to your configuration and 
then have a problem, BOOTCON can automatically re¬ 
store the previous configuration, reducing the need for 
emergency boot disks. The new comparison function lets 
you compare any two configurations, useful for seeing 
differences in large configuration files such as win. ini 
and system, ini. 

BOOTCON v2.1 costs $79. Registered users of version 
2.0 can upgrade for $18; competitive upgrades cost $35. 
For more information, contact Modular Software Sys¬ 
tems, 25825 104th Avenue SE, Suite 208, Kent, WA 
98031, (800) 438-3930 or (206) 631-5781; 
fax (206) 631-5779. 
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Database Design Tool Moves to Windows 

The Canonizer is a database design tool that pro¬ 
vides automatic normalization to third normal form and 
produces a variety of reports. You can use it to design 
new database models, re-engineer existing databases, 
generate code directly from design, produce design docu¬ 
mentation, and migrate database models across DBMS's. 

The new version is a Windows application that re¬ 
places the previous character-based version and includes 
online support. This version features attribute relation¬ 
ship diagram (ARD) modeling instead of traditional entity 
relationship diagramming. ARD modeling accepts infor¬ 


mation and queries as the database is built and the de¬ 
signer does not need to know a methodology before be¬ 
ginning to build. This version also lets you open more 
than one table at a time and removes limits on lengths 
of names, comments, and data types. 

The Canonizer v2.0.3 costs $1995 and supports Or¬ 
acle, Informix, Sybase, Ingres, Unify, DB2 or any ANSI- 
SQL compliant DBMS. For more information, contact Six 
Sigma CASE, Inc, 13456 SE 27th Place, Bellevue, WA 
98005-42 7 7, (800) 827-4462. 


Database Conversion Tool Gets Windows Interface 


N Systems has released Transform (formerly 
DBAPort) with a new Windows interface. Transform ap¬ 
plies reverse and forward engineering to support full or 
partial database conversion and migration for copy man¬ 
agement and redesign deployment between multiple 
RDBMS platforms and operating systems. You can use 
the product to convert and migrate schema definitions, 
table data, columns, indexes, grants, referential integrity, 
and views to and from DB2 for MVS, SQL/DS, Oracle v6.x 
and v7.x, Sybase SQL Server, Microsoft SQL Server, 
DB2/2, XDB, Informix, Ingres, and Gupta's SQLBase. 

Transform connects to the source database to read 
the system catalogs and determine the scheme defini¬ 


tions directly. Transform allows design and data changes 
from a development database to be deployed in a pro¬ 
duction database. Transform maps inconsistent source 
data types to defaults or user defined data types in the 
target database. The product also allows changes to the 
schema objects and data types with selective migration, 
archiving, and renaming of source/target tables, indexes, 
and columns. 

Transform costs $3,495 for the base system and an 
additional $795 for support for each database. For more 
information, contact NSystems, 2300 7 03rdAvenue NE 
Suite A Bellevue, WA 98004, (206) 450-0815; 
fax (206) 827-8 7 7 3. 


Flambeaux Updates Reference through DOS v6.2 


TECH Helpl is a hypertext database of technical infor¬ 
mation for DOS programmers. The new release includes 
an enlarged database of BIOS and DOS functions 
(through DOS v6.2) and covers system extension APIs 
such as DoubleSpace, DPMI, INT 33h mouse services, 
XMS, SVGA, and more. In all, TECH Helpl v6.0 provides 
over 100 technical articles and details over 800 API func¬ 
tions. The database consists of more than 1100 topics, 


nearly 3Mb (compressed to 1.1 Mb) of source text, data 
structure layouts, and diagrams, it includes 50 indexes to 
speed access to data. 

TECH Helpl v6.0 costs $99.95; upgrades cost $40. For 
more information, contact Flambeaux Software, 7 147 E 
Broadway #56, Glendale, CA 91205, (818) 500-0044; 
fax (818) 957-0194. 


New DLL Provides Spelling Checking API 

Spelling Sentry DLL is a new library that provides 
spell-checking services for Windows applications. The 
product comes with a 90,000-word main dictionary (two 
versions are provided: American and British/Canadian). 

The library also supports three application-supplied dic¬ 
tionaries: user, supplemental, and exclusion. The user dic¬ 
tionary is intended to contain words specific to the 
application's user (proper names, for example). The sup¬ 
plemental dictionary augments the main dictionary; you 
could use this to add technical terms for a given field, for 
example. The exclusion dictionary contains words that 
are to be considered misspelled, even if they exist in one 
of the other dictionaries. Your application can substitute 
dictionaries at runtime. 

The DLL API includes functions for determining if a 
word is misspelled, locating suggested alternatives for a 


misspelled word, adding and removing words from an 
application-supplied dictionary, and for saving and recall¬ 
ing words which the user wants to skip or replace with 
other words within a spell-checking session. On a 33Mhz 
80386 running Windows 3.1, the DLL can check more 
than 25,000 words per minute. The DLL currently sup¬ 
ports C and C++; Pascal and Visual Basic support is 
planned for 1Q94. 

The Spelling Sentry DLL costs $299 ($399 Cdn) or 
$585 ($779 Cdn) with source code. A toolkit that sup¬ 
ports compressed application dictionaries costs $149 
($199 Cdn). For more information, contact Wintertree 
Software Inc, 43 Rueter St, Nepean, Ontario Canada 
K2J3Z9, (613) 825-6271. 
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CodeBase Libraries Get Interface Designer, Report Writer 


Sequiter Software, Inc. has released version 5.1 of 
CodeBase, CodeBase++, CodeBasic, and CodePascal, li¬ 
braries for C, C++, Basic, and Pascal. The libraries now in¬ 
clude CodeControls, a Windows interface designer, and 
CodeReporter, a developer's report writer. 

CodeReporter v2.0 includes an 'instant report wiz¬ 
ard,' drag-and-drop object creation tools, a report API, 
and code generation capability. Generated reports can 
run under DOS, OS/2, Windows, Windows NT, Macintosh 
System 7, and UNIX. Developers can also distribute 
CodeReporter to their end-users, but must pay royalties. 

CodeControls v2.0 is a set of Windows interface con¬ 
trols for database applications developers. CodeControls 


Sl_SCOPE Turns PC into Serial Analyzer 

SLSCOPE is a software tool that lets you open up a se¬ 
rial line to view and interact with the communications 
channel. The product features fully configurable UART pa¬ 
rameters, multiple data capture formats (ASCII, EBCDIC, 
and hex), complete pin monitoring (DTR, DCD, Rl, CTS, 
and RTS), capture to disk, programmable keystroke mac¬ 
ros, data pattern search, 1 microsecond resolution time 
stamps, support for multiple text-mode resolutions (25, 


is data aware, so, for example, a listbox can be used to 
browse a database, or a combobox can be used to do da¬ 
tabase lookups while a search term is typed. The pack¬ 
age includes a Master Control that allows point-and-dick 
control of record positioning, searching, deleting, and un¬ 
doing previous actions. 

CodeBase v5.1 and CodeBase++ v5.1 each cost 
$495, and CodeBasic v5.1 and CodePascal v5.1 each 
cost $245. For more information, contact Sequiter Soft¬ 
ware, Inc, Suite 209,9644 - 54 Avenue, Edmonton, Al¬ 
berta, Canada T6E5V1, (403) 437-2410, 
fax (403) 436-2999 


28, or 43/50 line modes), a configurable flow control 
mechanism, and the ability to run on any two port ad¬ 
dresses with any two IRQs. 

SLSCOPE costs $149 and includes a manual and ca¬ 
ble. For more information, contact Software Innovations, 
Inc, 63 Rod c Cut Rd„ Newburgh, NY 12550, 

(914) 567-0805. 


FFE Updates RDBMS for DOS and Windows 


FirstSQL C is a RDBMS for C developers under DOS 
and Windows. It provides an embedded SQL precompiler 
for static and dynamic SQL and a C API. The new version 
supports Microsoft's ODBC interface, allowing FirstSQL C 
applications to access ODBC-compliant databases such 
as Oracle, SQL Server, AS/400, etc. This version also pro¬ 
vides a FirstSQL ODBC driver, so that other ODBC applica¬ 


tions (such as Access, Visual Basic, etc.) can access 
FirstSQL databases. FFE software also plans to release a 
new database server, FirstSQL Server, in early 1994. 

FirstSQL C v2.2 costs $395 for a single user, or $795 
for the network version. For more information, contact 
FFE Software, Inc, P.O. Box 1519, El Cerrito, CA 94530, 
(510) 232-6800;fax (510) 237-7433. 


DOS Pascal Async Library Adds Fax Support 


Async Professional is a communications library for 
DOS Pascal. The new version provides fax support, allow¬ 
ing programmers to: convert text, PCX, or TIFF files into 
compressed fax format; send or receive multi-page faxes 
on Class I, Class II, or Intel CAS fax modems at up to 
14.4K baud; automatically insert a fax header on each 
page; and convert from fax files to PCX files for editing. 
The new version also adds support for CompuServe B+ 


protocol and PKZIP 1 .x implode and LHA 2.x compres¬ 
sion methods. 

Async Professional v2.0 costs $189, is royalty-free, 
and includes full source code, documentation, popup 
help, example and demo programs, and free support by 
telephone, fax, and CompuServe. Upgrades cost $79. For 
more information, contact TurboPower Software, P.O. 
Box 49009, Colorado Springs, CO 80949-9009, 

(719) 260-664 l;fax (719) 260-7151. 


Geosoft Ships Map Tools 

GeoSoft has released two new products for Windows 
developers: Map Server 2 and Map Editor. Map Server 2 
is a new version of the company's map display and ma¬ 
nipulation toolkit for Windows. The new version offers 
faster map importing and drawing, and more intelligent 
redraws and scrolling. It also provides greater control 
over line styles and weights, polygon fill patterns, and en¬ 
hanced object querying. More data import formats are 
available, adding Atlas GIS, WMF Digital Chart of the 
World, and US Defense Mapping Agency VPF to existing 
formats, such as AutoCAD DXF and Ordnance Survey 
NTF Version 2. Map Server 2 allows points to be repre¬ 
sented by custom bitmap symbols, such as company lo¬ 


gos. Pan, zoom, export, and printing functions are sup¬ 
ported. 

Map Editor is an addition to Map Server 2 that lets 
you revise point, line, polygon, and text objects in maps. 
Map layers can be created or removed, objects can be 
modifed or deleted, and new objects can be added to a 
map. 

Map Server 2 costs £299 and Map Editor costs £149; 
both are Windows DLLs and are royalty-free. For more in¬ 
formation, contact Geosoft Ltd, Unit 3M, Springfield 
House, Hyde Terrace, Leeds LS2 9LN, United Kingdom, 

+44 532 344000; fax +44 532 465071. 
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New Tool Converts Norton Guide to WinHelp 


NG-2-HLP is a conversion tool that reads Norton 
Guide help files (. 09 ) and converts them into .rtf files. 

You can then feed the .rtf files to the Windows Help 
compiler (the tool also create the appropriate .hpj file) to 
create a Windows help file. The program has facilities to 
convert, compile, and test the help system. NG-2-HLP con¬ 


verts all hypertext links, colors, and styles, and can op¬ 
tionally change the help system font. 

NG-2-HLP costs $69.95 through the end of March. For 
more information, contact ExpoTech Corporation, P.O. 
Box 2935, Rohnert Park, CA 94928, (707) 588-8220; 
fax (707) 588-9220. 


New TUB Adds Project-Oriented Mode 

Burton Systems Software is now shipping TUB Ver¬ 
sion Control v5.1. The new release adds automated con¬ 
version of your source archives from PVCS or MKS RCS 
to TUB format, plus a new "project-oriented" mode. 
When converting PVCS or RCS archives, ail versions are 
converted (including branch versions), all version num¬ 
bers are preserved unchanged (except for punctuation), 
and version labels are translated into TUB "snapshots." 


TUB for DOS costs $139 for a single user or $419 for 
a 5-user network version. The OS/2+NT+DOS combo edi¬ 
tion costs $195 for a single user or $495 for a 5-user net¬ 
work version. For more information, contact Burton 
Systems Software, P.O. Box 4156, Cary, NC27519-4156, 
(919) 233-8128;fax (919) 233-0716. 


WindowBuilder Pro/V Ships for Win32 

Objectshare Systems is shipping WindowBuilder 
Pro/V for Win32, a version of their user interface tool for 
programmers using Smalltalk/V Win32. WindowBuilder 
Pro/V lets programmers interactively build user inter¬ 
faces and use inheritance to simplify design, develop¬ 
ment, and maintenance. Subpanes/V for Win32, a library 
of controls, is also available. Subpanes/V controls, such 
as a columnar listbox, spin buttons, bitmap buttons, and 
a bitmap pane, can be interactively placed and edited us¬ 
ing WindowBuilder Pro. 


WindowBuilder Pro/V for Win32 costs $395; up¬ 
grades from WindowBuilder Pro/V cost $75 and up¬ 
grades from WindowBuilder/V for Windows cost $245. 
Subpanes/V for Win32 costs $295; upgrades cost $50. 
For more information, contact Objectshare Systems, Inc, 
5 Town 8 Country Village, Suite 735, San Jose, CA 
95128-2026, (408) 727-3742;fax (408) 727-6324; 
CompuServe 76436,1063. 


QDB Updates Data Quality Software Tool 


QDB/Analyze is a software tool designed to identify 
defective data and manage improvements in corporate 
data quality. During design and development, QDB/Ana¬ 
lyze checks data against new data models; facilitates con¬ 
versions and re-engineering efforts by scanning data for 
accuracy, consistency, completeness, referential integrity, 
and timeliness; and examines data for errors during mi¬ 
grations to client/server environments, data warehouses, 
and data repositories. 


The new release offers an object-based MDI user in¬ 
terface, two new filter types, a redefined mechanism for 
generating data quality metrics, an icon toolbar, new 
WYSIWYG reporting and charting features, and faster fil¬ 
tering of large tables. 

QDB/Analyze v3.0 costs $3,500. For more informa¬ 
tion, contact QDB Solutions, Three Cambridge Center, 
Cambridge, MA 02142-1613, (617) 577-9205; 
fax (617) 577-9206. 


Transmission Library for Windows Released 


Hyperception, Inc. has released the Hypersignal for 
Windows Advanced Transmission Library, a set of design 
and analysis blocks for radio, wireline, and fiber optic 
transmission systems. These blocks are for use with the 
Hypersignal for Windows Block Diagram simulation soft¬ 
ware, and were designed by John C. Bellamy, author of 
Digital Telephony. The library blocks address baseband 
transmission models, modulation, demodulation, carrier 
and clock recovery, arbitrary filter design, system per¬ 
formance measures, and other miscellaneous functions. 

New filter design facilities are provided for modeling 
transmission links and designing and testing various 
types of equalizers. These new facilities incorporate opti¬ 


mization of filter parameters to match arbitrarily speci¬ 
fied responses of a single filter or an end-to-end system. 
Performance measure blocks are provided for bit error 
rate (BER) simulations, BER calculations, eye patterns, and 
jitter analysis. Additionally, there are blocks which ad¬ 
dress fiber optic light sources, fiber transmission paths, 
automatic peak control, elastic storage, and UARTs. 

The Advanced Transmission Library costs $1,495 for 
single units. For more information, contact Hyperception, 
Inc, 9550 Skill man, LB 125, Dallas, TX 75243, 

(214) 343-8525; fax (214) 343-2457. 
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WUIMAN’s User Interface 



Borland C++ v4.0 
Symante/c C++ v6.1 
Visual C++ vl .5 


This is the eighth in a series of columns about the design and implementa¬ 
tion of WUIMAN (a Windows User Interface MANager). Unlike other GUI-build- 
ing tools under Windows, WUIMAN links with your application and allows you 
(or even end users) to create, modify, and extend your user interface (which is 
described by a simple tree-structured database) at any time - there is no test 
mode, since your application and its user interface are live" at all times. This 
installment describes WUIMAN object attribute properties and the user interface 
for manipulating them. 

Attribute Inheritance 

One of the many design issues I've waffled on in this project is precisely 
how attribute inheritance should work. I can best describe attribute inheritance 
with the concrete example of fonts. Your Windows application may use fonts 
in a variety of places (window captions, button labels, static text, menus, list- 
boxes, and so on). I wanted WUIMAN to give the user interface designer the 
ability to easily be consistent in using things such as fonts. For example, the 
user interface designer for a program may decide that all button labels will be 
in a 9-point Helvetica font. If it is later discovered that a 9-point font is too 
small, I want the designer to be able to change all the button label font sizes 
by changing a single WUIMAN object attribute. 

On the other hand, enforcing a single attribute value throughout a program 
is a little too rigid. The user interface designer might first specify that nearly all 
buttons should be gray with black text in 9-point Helvetica, but should be able 
to decide later that one particular button needs to be black with red text in 
16-point Helvetica. The way I implemented the ability to specify general behav¬ 
ior that is modifiable in specific cases is with attribute inheritance. 

In C++, inheritance is a static thing. If you change a base class, you must 
recompile your project in order for any derived classes to inherit the changed 
base behavior. In WUIMAN, inheritance is a dynamic thing. If you change the 
'Font' attribute of a particular node in the WUIMAN tree, WUIMAN must dy¬ 
namically update any nodes below that one that happen to inherit the "Font' 
attribute. This has the potential for violating the principle of least surprise for 
WUIMAN programmers, since setting a single attribute value could cause attrib¬ 
utes to be set in a large number of other nodes. 


Ron Burk 


Ron Burk is the editor of Windows/DOS Developer's Journal and has been a program¬ 
mer for 72 years. You may contact him at Burk Labs, P.O. Box 3082, Redmond, WA 
98073-3082. CIS: 70302,2566. Internet: ronb@rdpub.com (“ . . . luunetlrdpublronb”). 












The person I really do not want to surprise is the end 
user, so I require one aspect of WUIMAN's attribute inheri¬ 
tance to be implicit. Suppose your interface is described by 
a WUIMAN tree whose top-level node contains a "Button- 
Font" attribute set to 'Helvetica' that all its descendants 
inherit. Suppose, further, a user who has changed a but¬ 
ton on some low-level dialog so that 'ButtonFont' is 
"WingDings" (to be able to display a symbol instead of 
text, for example). Said user would likely be unhappily sur¬ 
prised if a change to the top-level "ButtonFont' attribute 
wiped out the lower-level customizations. For that reason. 


Listing 1 viwep.c — A vendor-independent WEP 


/* 

* viwep.c - Vendor-independent WEP. 

*/ 

//include <windows.h> 

//if defined(_MSC_VER) 

// Note: .def file must also list WEP in the EXPORTS section 
// in order to get Microsoft’s WEP linked in and exported. 

// Borland’s design is nicer, not requiring you to 
// maintain a .def file just to get static destructors called, 
extern ”C” { 

int CALLBACK _WEP(int /*ExitCode*/) 

{ 

OutputDebugString("Microsoft WEPO invoked\r\n"); 
return 1; 

} 

}; 

#elif defined(_BORLANDC_) 

// Borland does it right, except for very nasty 4.0 EH bug! 
int CALLBACK WEPtint /*ExitCode*/) 

{ 

OutputDebugStringCBorland WEPO invoked\r\n"); 

return 1; 

} 

#el1f defined(_SC_) 

// hard to believe, but Symantec C++ apparently does not 
// supply a WEP or call static destructors for you! 

// Here's my undocumented workaround... 

extern "C" { 

//include <process.h> 

int CALLBACK _export WEP(int /*ExitCode*/) 

{ 

OutputDebugStringC'Symantec WEPO invoked”): 

// do work that Symantec runtime should have 

_dodtors(); 

return 1; 

} 

}; 

//elif (1) 

//error "UNKNOWN COMPILER TYPE" 

#e ndif 

/* End of File */ 


I want any change to an inherited attribute to cause that 
attribute to no longer inherit changes from its parent 
node. Again, this behavior could be surprising to the pro¬ 
grammer (setting an attribute has the side effect of mak¬ 
ing it no longer inherited), but I think the result is much 
more convenient for the person designing and maintain¬ 
ing the user interface. 

Inheritance Details 

The details of attribute inheritance, as well as some 
other attribute behavior, are implemented in TMuiBaseAt- 
tribute::Set(), the set function for the base class that all 
attributes inherit from. All attributes have four associated 
bits, as shown in the dialog box in Figure 1. The "persist¬ 
ent' bit means that any changes to the attribute are auto¬ 
matically and immediately written to the WUIMAN disk 
database so that they will persist to the next invocation of 
WUIMAN. The "read only" bit prevents any changes to the 
attribute, except via inheritance. The "inherited" bit deter¬ 
mines whether this attribute inherits any changes made to 
the same attribute in its parent node in the WUIMAN da¬ 
tabase. The "inheritable" bit controls whether this attribute 
can be inherited by any children of the current node. 

The detailed meaning of these bits lies in the imple¬ 
mentation of TMuiBaseAttribute: :Set(), which is (eventually) 
called whenever an attribute value is set. The simplified 
pseudocode for TMuiBaseAttribute: :Set() looks like this: 

if(persistant bit is set) 
save new value to disk 
turn off inherited bit 
if(inheritable bit is set) 

for each child node with this attribute 
if(attribute’s inherited bit is set) 
set child node attribute to new value 
set inherited bit 

If a child node has an attribute of the same name (I 
should perhaps also require it to be of the same class or a 
descendant of the current attribute class) whose inherited 
bit is set, then TMuiBaseAttribute: :Set() will set its value, 
resulting in recursion. Note that after setting the attribute 
of a child node, the algorithm has to set that attribute's 
inherited bit, since any change to the attribute value im¬ 
plicitly turns that bit off. 

Bug++ of the Month 

The hands-down winner for the Bug++ of the Month is 
Borland C++ v4.0, which contains a rather spectacular 
bug. My definition of "spectacular' is this: you can take a 
bug-free C++ DLL that works correctly under Borland C++ 
v3.1 (and Symantec and Microsoft, for that matter), just 
recompile and relink with Borland C++ v4.0, and end up 
with a DLL whose startup code will trash data in any non- 
Borland application that accesses the DLL - that is spec¬ 
tacular! Even though Borland wins the competition this 
month, both Microsoft and Symantec offer such hostile en¬ 
vironments for creating C++ DLLs that I want to give them 


Page 80 — Windows/DOS Developer’s Journal 


May 1994 




honorary mention. The problem I will 
look at is the problem of static de¬ 
structors. 

C Windows programmers know 
that a DLL has an entry point called 
LibMainO and a function that gets 
called at termination, called UEPO. 
Now suppose you have been build¬ 
ing a DLL in C and you switch to 
C++ and start using C++ features. 
One feature you might reasonably 
take advantage of is static construc¬ 
tors and destructors. 

Suppose your application has 
code like this: 


WuiMan vO.O 


S- 

Classes 
” TContainer 

- TAttributelnt 

- TAttributeString 


Delete 

New Child 

Insert 

Append 


11 


Borland C++ u4.0 


Method 


WUIMAN Property Detail 

/.Compiler 
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Class: T 
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P Inherited 
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W/D 

1 D J 


W/D 

" D J 


W/D 
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W/D 
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W/D 
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W/D 
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W/D 
" D J 


W/D 
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Figure 1 Editing WUIMAN attributes 


class Resourcestring { 
public: 

ResourceString(int Resourceld); 

-ResourceStringO; 
const char *String() { return String_; } 
private: 

char *String_ 

}; 

static Resourcestring 
ErrorMessage(IDS_ERR_NETWORK_NOT_AVAIL); 

C++ guarantees that the object ErrorMessage will exist (get 
constructed) before your application begins executing and 
that ErrorMessage: :~ErrorMessage() will get called after your 
application code terminates. But the C++ language specifi¬ 
cation specifies nothing about DLLs, so what should hap¬ 
pen if this code is used in a DLL? Clearly, ErrorMessageO 
should get created before LibMainO is called and should 
get destroyed after UEPO is called. Sounds pretty simple, 
but apparently it was beyond the capabilities of both Mi¬ 
crosoft and Symantec compilers. 

Borland: Had it Right, Broke it Bad 

Borland C++ v3.1 actually had it right. It called static 
constructors before calling LibMainO and arranged for 
static destructors to be called after your UEPO returned. 
There was no need to enclose your functions in extern "C" 
{ } - if you just didn't think about LibMainO, UEPO, and 
static destructors, then they probably worked correctly for 
you automatically. Alas, Borland's excellent behavior is 
more than cancelled out by a terrible bug in Borland C++ 
v4.0. It turns out that Borland's implementation of excep¬ 
tion handling in DLLs requires it to communicate with the 
calling application via a specific memory location in the 
calling application's DGROUP. Borland C++ v4.0 applications 
therefore reserve variable space at the correct offset in 
DGROUP. Of course, any application that calls your DLL that 
did not reserve these variable locations (most any applica¬ 
tion that was not compiled with Borland C++ v4.0) will get 
its DGROUP scribbled on by the DLL's exception handling 
startup code. 


You might think that this bug only affects those brave 
souls who are starting to write exception-handling code in 
their C++ programs. Wrong! I merely recompiled and re¬ 
linked a simple C++ DLL with Borland C++ v4.0 and the 
result was, whenever uinhelp.exe used my DLL, it would 
eventually crash. After tedious hours of trying to narrow 
the problem down, I realized that if my DLL contained any 
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reference (even a reference that never got invoked) to the 
global new operator, it would crash the calling application. 
At that point, I got on Borland's CompuServe support fo¬ 
rum and it turned out that this bug had actually already 
been noted - the problem is that using the new operator 
causes the exception-handling code to be linked,in, even 
if you are not explicitly using exceptions anywhere in your 
program. 

In a grim replay of Borland's license controversy, some 
Borland support members initially took the position that 
this was not really a bug, that it was required behavior to 
implement exception handling. Of course, this attitude ex¬ 
cited many customers, who might reasonably have ex¬ 
pected a big red warning on the Borland C++ v4.0 pack¬ 
age that said 'Borland C++ is no longer usable for creat¬ 
ing general-purpose DLLs' if Borland really thought this 
was acceptable behavior. 

The current workarounds are fairly grim: recompile and 
relink the entire Borland DLL runtime with exception han¬ 
dling turned off, or avoid exception handling in your code 
and write your own global new. Whatever you do, if you 
are creating a DLL for use with non-Borland applications, 
use TDUMP on the .exe and verify that no exception-han¬ 
dling code is linked in (you'll see some fairly obvious, 
funny-looking C++ function names); otherwise you may 
be shipping a time bomb to your customers. 

Michael Hyman of Borland has reported that they plan 
to post a runtime library without exception handling in 
the short term, followed by a compiler patch. Both solu¬ 
tions should be available by the time you read this. Check 
on the BCPPWIN forum of CompuServe for the latest infor¬ 
mation. 

Microsoft: Making It as Hard as They Can 

How does Visual C++ vl.5 handle static destructors? 
Well, if you simply have C++ functions called LibMdinO 
and UEPO, your static destructors do not necessarily get 
called and neither does your MEP()\ Rather than explain all 
the many ways that you can fail to get DLL static destruc¬ 


tors called with Visual C++, I will reveal the barely-docu¬ 
mented voodoo that Microsoft recommends that you use. 

The secret is that Microsoft's DLL runtime library con¬ 
tains a UEPO (a C function) that first calls JEPO (a C func¬ 
tion) and then invokes static destructors. So, if you wish to 
have a function in C++ that gets called when your DLL 
terminates, you must declare it something like this: 

extern "C" { 

int CALLBACK _WEP(int code) { 

OutputDebugString( 

"Usability Lab Needed!\r\n”); 

} 

}; 

But that is not enough, because by default, Microsoft's DLL 
runtime UEPO (the one that will invoke static destructors) is 
not linked to your program when you use the command¬ 
line tools. To get it linked in, Microsoft recommends you 
include the following in your .def file: 

SEGMENTS ’WEPJEXT’ FIXED PRELOAD 
EXPORTS 

WEP @1 RESIDENTNAME 

This is hardly a convenient design, given the fact that fail¬ 
ure to get everything just right means that static destruc¬ 
tors will silently fail to be called. Also, the Visual C++ 
documentation does not mention static destructors in the 
description of its UEPO scheme. Normally I use the _export 
keyword to avoid having to maintain a .def file, but 1 
could not find any way to get Microsoft's UEPO linked in 
without manually inserting it into the EXPORTS section. 

Microsoft should just copy Borland's scheme (except for 
the nasty exception handling bug) and make LibMainO, 
UEPO, and static destructors work the way C++ program¬ 
mers might reasonably expect. Failing that, Microsoft 
should at least point out in the documentation that fail¬ 
ing to insert the correct incantations can prevent correct 
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language behavior in their DLLs. Finally, Microsoft should 
make up their minds once and for all whether the UEP() 
must be FIXED or not under Windows 3.1. FIXED memory in 
DLLs wastes precious conventional memory and can lead 
to Windows being unable to launch applications. Unfortu¬ 
nately, while some Microsoft support personnel are saying 
that the UEP() need not be FIXED under Windows 3.1, Mi¬ 
crosoft's most current documentation (Visual C++ 1.5 and 
the MSDN CD-ROM) expresses contradictory views - I've 
been trying to get a definitive statement from Microsoft 
on this subject for months. 

Symantec: Static Destructor? What s That? 

Symantec's problem with static destructors in DLLs has 
the virtue of being easy to describe: they are never in¬ 
voked under any conditions! Amazingly, the Symantec 
DLL runtime contains no UEPO of any kind, so you can 
declare your own UEPO (which will get called only if you 


declare it as a C function) or do most anything else you 
want and static destructors will not be called. The Syman¬ 
tec documentation, ever sparse, does not mention static 
destructors in DLLs at all. 

I went poking through the Symantec runtime source 
and discovered a function called _dodtors() (in C++ com- 
piler-ese, this would be pronounced 'do destructors") that 
apparently handles invoking static destructors for applica¬ 
tions. When I defined a C UEPO and called this function, 
static destructors got called correctly. When I asked Sy¬ 
mantec about the lack of support for static destructors in 
DLLs, Walter Bright of Symantec referred me to this func¬ 
tion, so this is apparently a workaround that Symantec 
approves of. 

It's hard to suggest improvements to an implementa¬ 
tion that simply doesn't exist. It would be nice if Symantec 
C++ could implement static destructors as Borland did in 
its C++ v3.1, but any reasonable attempt to support this 
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show you how to find an assignment abroad. Call us to 
receive a membership package for this new global 
organization of software professionals. 

ICPA 

350 Townsend Street, Suite 301 ^ 

San Francisco, CA 94107 USA 

24 hour Tel: 1 (415)695-7618 

24 hour Fax: 1 (415) 543-3022 1K £- 
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Phone Sound: Simple! 


For Windows/DOS Voice Mail & Fax Developers 




Professional 
Tools for 
your Voice 
Mail, Fax & 
Audiotex 
Applications 


1. Create fantastic prompts 
and save time with VFEdit <§>' 
Record, crop, cut, copy, paste, 
mix, fade, echo, volume & 
more with your Dialogic™ 
D4x/12x boards 

2. Add Voice Mail power to 
your MS Windows apps with 
Tl/FDLL « our Tel l/F 
Dynamic Link Library 

3. Audio Tool Box™ 
converts to and from 


Multimedia Wave (16. 8 & 
MS ADPCM), linear 16 & 
unsigned 8. plus Dialogic 4 & 
8 at any sample rate' 

4. Scribe Transcription 
Utility for DOS plays digital 
audio files in the background 
without voice mail hardware 1 

5. Add Text-to-Speech 
capability to your apps with 
Vox Fonts™, our "software 
only" text-to-speech library 1 


Order Now! 1-800-234-VISI 


I Voice Information Systems: 24 N Mcrion Ave. Brvn Mawr. Pa 19010 

Tel 215-747-5035/ BBS 310-392-6610/ Fax f-800-234-FXIT 
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DICE IS LOOKING FOR... 


...data processing, engineering and 
technical writing professionals to fill 
open positions nationwide. DICE is 
a FREE online job search service 
providing detailed information about 
current contract and full-time 
positions across the USA. It’s a 
confidential, easy to use, no cost 
way to search for a new job. 



DATA PROCESSING 
I NDEPENDENT 
CONSULTANT'S 
E XCHANGE 


ONLINE Number 
515 - 280-3423 


Contact DICE via 1200/14400 baud 
Modem, 8-N-1. 

A service of D&L Online, Inc. 
515-280-1144 
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Winnows source, 
WinToAsm can deliver Itl 

WUTMsm 

Disassembles MS-Windows EXEs, 
DRVs, DLLs, and VxDs, by 
segment, range, or export. 
Labels exported and imported 
functions, VxD services, 
control proc, API entry, etc. 
Generates segment, export, 
import, and header tables. 

Supports batch-mode tagging of 
functions and data items 

MesToRC 

Decompiles resources to a RC file. 

Vextnct 

Extracts VxDs from Win386. 

Ail for only $94,951 
30-day Money-Back Guarantee 

Eclectic Software 

937 Jungfrau Court 
Milpitas.CA 95035 
(408) 262-3264 Voice/FAX 
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language feature would be a welcome change. Even sim¬ 
ply mentioning in the documentation that you can declare 
your own UEP() as a C function and manually call 
_dodtors() yourself to get correct language behavior could 
save customers some pain. 

Walter argues that some programmers might want 
static constructors and destructors called on a per-applica- 
tion basis, so making the programmer call explicit func¬ 
tions provides that flexibility. That doesn't strike me as 
particularly reasonable, and in any case, the Symantec 
runtime already implicitly calls static constructors, so the 
programmer really does not have a choice of schemes. 


Summary 

viuep.c (Listing 1) contains some code that sums up the 
dismal state of DLL static destructors in the three compil¬ 
ers I use. I can use this code whenever I need to make 
sure that both a termination function and static destruc¬ 
tors are called. I sure hope that support for C++ DLLs will 
improve in the next releases of these compilers! 

This month's code disk has the complete WUIMAN 
source for the project to date, including code from past 
issues. The code disk is widely available via sources listed 
in the table of contents. □ 



Developer's 

Marketplace 


The Time 
Has Came... 

...to send for the latest copy of 
the free Consumer Information 
Catalog. It lists more than 200 
free or low-cost government 
publications. Send your name 
and address to: 

Consumer Information Center 
Department TH 
Pueblo, Colorado 81009 

U.S. General Services Administration 



We Understand The 
Programmer's Mind 


When the country's top firms look for the 
best developers available, they turn to 
Bateman. Why? Because we specialize in 
Microsoft Windows, NT, OS/2 and Macin¬ 
tosh recruiting nationwide. So if it's time for 
a career move, give us a call. We under¬ 
stand your skills, and the marketplace for 
them... we understand you. 

□Bateman Inc. 

5847A Uplander Way 
Culver City, CA 90230 
Tel: 310-641-4100 Fax: 310-641-2900 
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Diskette I/O 

Code Libraries 
Device Drivers 

VxDS 

Special Hardware 


Software for Conversion, 
Duplication, Analysis, 
and Data Recovery 


WE SPECIALIZE IN "ALIEN" 
NON-PC FORMATS. 

Write or call for a product brochure! 

VtlHpV POBox5700 
kJJ Vl-V^A. Eugene, OR 97405 

(800) 43-SYDEX or (503) 683-6033 
FAX (503) 683-1622 



Tools for Novell's Btrieve® 


ltsupport III Bsupportll 

Bcdit 3.0 - Btrieve file vicwcr/cdilor. 
Banalyze 2.0 - Btrieve app. debugger. 

Brun 2.2 - BUTIL replacement plus source. 
Bcrcate 2.0 - file creation utility. 

Beheck 2.0 - Btrieve file analyzer. 

Xsupport 1.0 - build data dictionary 
(.DDF) for Access, OV, 
Crystal Rpts. 

Xport 2.0 - export/import CDF, SDF, 
dBASE. 

Call for information on additional 
products and FREE demo! 

Information Architects, Inc. pj i: ( 800 ) 359-2721 
3130 Pine Tree Road (517) 887-8000 

Lansing, MI 48911 Kax: (517) 887-2360 
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Macro 
Language 
"To Go" 


Easily add Netlogic’s full featured 
macro language facility to your 
Windows application -- at a fraction of 
the time and cost of developing it your¬ 
self. Seamless integration. Full basic 
syntax. Integrated editor and debug¬ 
ger. Extendable and modifiable. For 
more information: Netlogic Inc., 915 
Broadway, New York, NY 10010. 
Phone 800-638-0048. Fax 212-533-9524 

ProMacro m 

Your Application's Shortcut to Power 
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HE 

[TREASURE- 
HUNTERS 

In the world of software, it is 
all too easy to lose a valuable 
treasure: by editing and saving 
a program, overwriting a vital 
previous version. 

To prevent you from having to 
search in vain for buried treasures, 
ARIS VERSION TRACKING SYSTEM 
for Windows enables you to access 
and use previous program versions. 
AVTS. A gem of a program 
at a diamond price. 


ARIS 

Information-Systems 


Parkstr.2,85646 Anzing, Germany 
Phone +49-8121-45624. Fax +49-8121-45625 1 
From the USA, call 
Phone 01149-8121-45624 
, Fax 01149-8121-45625 
L Email: CompuServe 100042.1707 

wt'a 
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IMWHelp 


Window/ Help Authoring Tool 


Professional quality help files 
in 1/4 the time!! 

• Edit text directly in IMWHelp 

• Build hypertext links to: topics, 
definitions, subjects 

• Glossary automatically created 

• Bitmaps incorporated 

• Desktop publishing features 

• Print topics, help file, customized 
reports 

• Spell check, replace verify/all 

• Easily reorganize topics, subjects, 
keywords 

• Uses Microsoft Help Compiler 

Single User: $89.95 

MC & Visa accepted, Shipping additional 

Call: IMCSI (212)319-1903 

425 Madison Ave., New York, NY 10017 
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Add ZIP/UNZIP Power to your app's! 


DynaZIPcomp-eSfon 

Toolkit for Microsoft*Windows 


Finally there’s an intelligent and easy 
way to incorporate reading and writing 
of industiy standard ZIP files into your 
Windows programs, without having to 
“shell" to DOS. 

DynaZIP is a high-qualily ROYAL1Y-FREE 
set of DLLs that give you a robust API for 
reading, testing, creating, writing, and 
updating your ZIP files. Supports C/C+ + 
and VB; includes source code for a 
high-quality Windows-based ZIP shell, 
comprehensive test/diagnostic tools, 
and full documentation/help system. 
Versions available for Win3.1 and NT. 


Now only $ 249.00 w/30-day 
no-risk guarantee! 

Call today, toll free: (800) 962-2949 


Inner Media. Inc.. Hollis NH USA (603) 465-3216. fax (603) 465-7195 
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1 - 

I Does your company 
provide tools, products, 
or services for advanced 
Windows programmers? 
Then reach over 21,000 
serious programmers in: 

Windows/DOS 

□ developers journal 

Call 913-841-1631 today for 
information about 
advertising opportunities in 

Windows/DOS Developer’s Journal. 

Advanced. Serious. 

Technical. 


I Brian Osborn - Continental Europe. 

+49 431-396895 

I Ed - East I Christine - Midwest I Edwin - West 
913-841-1622 1913-841-6733 1913-841-1626 


C and C++ DOCUMENTATION 


! AUTOMATED DOCUMENTATION ! 

• C-CALL ($69) Graphic-tree of caller/called 
functions, cross-ref, file/function index. 

• C-CMT ($69) Creates/inserts/updates 
comment-blocks for each function, listing 
the functions and identifiers used by it. 

• C-METRIC ($59)Counts path complexity, 
counts comments, code, 'C' statements. 

• C-LIST ($69) Lists and action-diagrams, 
or reformats into standard formats. 

• C-REF ($59) Creates cross-reference of 
local/global/define/parameter identifiers. 

• SPECIAL : C-DOC ($199) All 5programs 
integrated as DOS program (<15,000 lines) 

• NEW! C-DOC Professional ($299) 

DOS, OS/2, Windows. 3-ring binder/case. 
Processes 150,000 lines, deterred reports. 

• 30-DAY Money-back guarantee CALL NOW 


SOFTWARE BLACKSMITHS 1 

6064 St Ives Way, Mississauga 
ONT, Canada Voice/Fax (411 

NC. 

i 

1-446 

] 

L5N-4M1 Demos/BBS (tn 


cm 


see AD INDEX for our larger ad 
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USING C++ OBJECTS WITH 
SQL RDBMS’s??? 

The Solution Isn’t Obvious, It's 

SUBTLEWARE™ FOR C++/SQL 


* Uses your C++ Class 
Definitions 

* Fully supports the C++ 
Object Model 

* Automatically generates 
SQL mapping code 

* Provides Portable Object 
Persistence across a variety 
of SQL RDBMS’s 


* Works with your existing 
RDBMS’s and tools 

* Shortens your development 
and maintenance time 

* Fits into most C++ 
environments, including 
Borland C++ and Visual 
C++ 

Wi 

Subtle Software 
Inc. 


^ ANSI SQL Engine \ 
Introductory Price $299 

CALL 1-508-663-5584 

30 Day Money Back Guarantee 
Ask about availability of other 
< Database Specific Modules/ 


1 Albion Road 
Billenca, MA 01821 
FAX: 508-663-5685 


© 1994 Subtle Software, Inc SubOeware™ is a trademark of Subtle Software. Inc 
Other product names are trademarks of their respective holders 
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IPX VBX/DLL 
NetBIOS VBX 


These custom controls allow a Visual 
Basic developer to write distributed, 
client/server applications. A separate 
Windows dynamic-link library (DLL) is 


available for IPX. 



NetBIOS $99 

itrunswith * 
NetWare 

IPX/SPX $295 


itn.— 


ipiVuy 


10201 W. Markham, Ste. 101 
Little Rock, Arkansas 72205 
Tel (501) 221-3600 • Fax (501) 221-7412 


OPTLINK 5.0 SU- 


Now shrinks program file sizes 
another 50%! 

Enables Windows developers to generate compressed 
self-loading executables (.EXE) and Dynamic Link Librar¬ 
ies (.DLL), thus reducing file sizes an additional 50%. 

Benefits include: 

• Loads applications faster 

• Saves you $'s - fewer 
diskettes to ship 

• Speeds up installation time 

• Complicates reverse 
engineering 

• Reduces your customers' 
disk requirements 

• Only requires relinking 
Other reasons to use OPTLINK: 

• Fastest Windows linking • Builds the smallest programs 

• Unrivalled capacity • No limits on debug information 

• Eliminates RC, IMPLIB, IMPDEF 

TO ORDER CONTACT: 

SLR Systems , Inc. 

1622 N. Main Street. Butter, PA 16001 USA 
Phone: (412) 282-0864: Fax: (412) 282-7965 
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Introducing... 


The Only 

■ ■ T ■ 


That Lets You 
Develop 
Without Limits! 


With Applicat, you’re the con¬ 
ductor. Orchestrate a world of 
Windows® macros across multiple 
applications. Limits? There are 
none. 

The Applicat-based language 
engine (a.b.l.e.) lets you use any 
Windows® command (even those 
embedded in other applications) 
in your own macros. Use DDE, 
OLE, API and more, in any com¬ 
bination. You get over 100 library 
and 500 API functions, too. 

Use Macro WorkBench to build 
your own data base of commands. 
Then, complete your design with 
buttons, menus and dialog boxes. 

So much power, at a price you 
can’t pass up. The complete 
Developer Edition is only $395. 
Or, consider the Professional 
Edition for only $ 1,495—with 
added utilities and the ability to 
compile your macros into royalty- 
free .EXE files. 


USA and Canada: 

InControl Systems Inc. 

(800) 275-6380 
Fax (214)219-6906 
Compuserv®: 74147,3407 
Internet®: applicat@onramp.net 

Elsewhere: 

COMPATYPE GmbH 
Roonstr. #23 A 
Karlsruhe, D-76137,Germany 
Tel.0721/98146-0 
Fax 0721/98146-10 
CompuServe: 100265,3022 

Windows is a trademark of Microsoft Corporation. 
AppliCat & a.b.l.e. are trademarks of COMPATYPE (R) 
GmbH 
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AVOID EMBARRASSMENT! 



“A customer found a bug in 
our software with a tool ' 
called BOUNDS-CHECKER .. . 


Why aren't we using 
BOUNDS-CHECKER?” 


I 


Use BOUNDS-CHECKER™ V2.0 For Windows, The Automatic Bug Finder! 



Nu-Mega Technologies Demo 




A 


BCHKW-DEM03.EXE 


jfile Action Settings yffndow 


MSiSa I >15* ream r-uffiS laTCl 


if (iPrame — 8) 

pPal->palV«rsion * 0; 
hPal ■ CreatePalette (pPal); 

imrr \m\immMmmn 



Whether you're the boss, the QA Manager or the programmer, it's your responsibility to ensure that 
your company's Windows programs are "bug-free" before they get into the hands of customers. 
If you're developing under C or C++, producing a "bug-free" Windows product is no longer a long 
and stressful experience. 


Announcing BOUNDS-CHECKER V2.0 For 
Windows, the software developer's "safety-net". 
Quickly and easily eliminate the hardest-to-find 
Windows errors that can take days - even weeks 
to find like: 

• API Parameter Errors 

• API Return Value Errors 

• Data and Heap Corruption 

• Resource Leakage Problems 

• Memory Leakage Problems 

• Processor Faults 

HOW IT WORKS - BOUNDS-CHECKER works by 
transparently setting hundreds of breakpoints within 
your program to monitor its behavior. When a bug 
is detected, BOUNDS-CHECKER immediately stops 
your program and pops up showing the problem. 
You can then inspect your program's source, vari¬ 
ables, stack and heap ... with BOUNDS-CHECKER's 
powerful display windows, 

EVENTLOGGING - BOUNDS-CHECKER nowlogs 
all Windows events. Many Windows bugs are diffi- 
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cult to find because of the event driven, multi-tasking, mes¬ 
sage based nature of Windows. BOUNDS-CHECKER V2.0 For 
Windows introduces an event logging and display capability 
that captures all Windows messages, API calls, API returns 
and other events. The information is displayed in a high-level 
overview that lets you see how your program is Interacting 
with Windows. When you want to see more detail, simply click 
to see a section expanded in great detail. 

EASY TO USE — Unlike other debugging tools, there's no 
learning curve with BOUNDS-CHECKER. Simply select your 
program's name from BOUNDS-CHECKER's menu; all the rest 
is automatic. There is nothing to link-in and no macros to 
compile into your program. All this plus the functionality of a 
heap checker, super spy utility, debug kernel, API debugger, 
and a post mortem tool into a single comprehensive auto¬ 
matic bug finder, 


BOUNDS-CHECKER Trapping a Parameter Validation Error 



For even greater debugging power get the 
Nu-Mega Power Pack! The Power Pack 
combines BOUNDS-CHECKER and Soft-ICE 
for Dos and Windows all bundled at great 
savings that put you in total control of both 
environments. And to make things even 
better you save over $400 and it comes in 
the great carrying case shown here. 

Call Today 


Call now for overnight delivery. 

BOUNDS-CHECKER V2.0 For Windows... Only $249 
BOUNDS-CHECKER For MS DOS... $199 
Order both versions & SAVE $150... Only $298 


BOUNDS CHECKER, SOFT-ICE, AND NU-MEGA TECHNOLOGIES are trademarks owned by Nu-Mega Technologies, Inc. All other trademarks are owned by their respective owners. 
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